fhirsmith 0.18.2 → 1.0.0

package/ips/store.js

@@ -68,6 +68,7 @@ const SCHEMA = `
     patient_birth   TEXT,
     comp_date       TEXT,
     comp_title      TEXT,
+    nationality     TEXT,               -- the nation the document is from (nationality step), if known
     json            TEXT NOT NULL,
     -- the analysed copy: the document as the processing steps adorned it (pipeline.js)
     analysed_json   TEXT
@@ -109,6 +110,7 @@ const SCHEMA = `
     version     TEXT NOT NULL,      -- the package version
     url         TEXT NOT NULL,      -- the canonical URL of the IG's profile on Bundle
     jurisdiction TEXT,              -- the country (ISO 3166 two-letter code) or region (UN M49 three digits)
+    snomed_edition TEXT,            -- the SNOMED CT edition the IG takes for granted (its module id), if any
     updated_ms  INTEGER NOT NULL,
     UNIQUE (package_id, version)
   );
@@ -127,6 +129,20 @@ const SCHEMA = `
     ref      TEXT
   );
 
+  -- each time the processing pipeline was started on a document, and how it ended: running,
+  -- finished (whether or not the document was fine), failed (the pipeline threw), or
+  -- interrupted (the server stopped while it ran). For the daily report. No foreign key: a run
+  -- still happened after its document is deleted
+  CREATE TABLE IF NOT EXISTS pipeline_runs (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    doc_id      INTEGER NOT NULL,
+    started_ms  INTEGER NOT NULL,
+    ended_ms    INTEGER,
+    outcome     TEXT NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_pipeline_runs_started ON pipeline_runs(started_ms);
+  CREATE INDEX IF NOT EXISTS idx_pipeline_runs_running ON pipeline_runs(outcome, doc_id);
   CREATE INDEX IF NOT EXISTS idx_documents_project ON documents(project_id, id);
   CREATE INDEX IF NOT EXISTS idx_documents_status ON documents(status, id);
   CREATE INDEX IF NOT EXISTS idx_ips_index_doc ON ips_index(doc_id, res, param);
@@ -171,7 +187,7 @@ function summaryOf(bundle) {
 
 /** A national_profiles row, as the store gives it. */
 function nationalProfileOf(r) {
-  return { id: r.id, jurisdiction: r.jurisdiction || null, packageId: r.package_id, version: r.version, url: r.url, updated_ms: r.updated_ms };
+  return { id: r.id, jurisdiction: r.jurisdiction || null, packageId: r.package_id, version: r.version, url: r.url, snomedEdition: r.snomed_edition || null, updated_ms: r.updated_ms };
 }
 
 class IpsStore {
@@ -194,7 +210,7 @@ class IpsStore {
       insertIndex: this.db.prepare(`
         INSERT INTO ips_index (doc_id, res, param, type, str, str_lc, sys, code, lo, hi, ref)
         VALUES (@doc_id, @res, @param, @type, @str, @str_lc, @sys, @code, @lo, @hi, @ref)`),
-      readDoc: this.db.prepare('SELECT id, project_id, received, received_ms, source, status, status_message, processed_ms, size, patient_name, patient_gender, patient_birth, comp_date, comp_title, json, analysed_json FROM documents WHERE id = ?'),
+      readDoc: this.db.prepare('SELECT id, project_id, received, received_ms, source, status, status_message, processed_ms, size, patient_name, patient_gender, patient_birth, comp_date, comp_title, nationality, json, analysed_json FROM documents WHERE id = ?'),
       saveAnalysed: this.db.prepare('UPDATE documents SET analysed_json = ? WHERE id = ?'),
       deleteDoc: this.db.prepare('DELETE FROM documents WHERE id = ? AND project_id = ?'),
       countDocs: this.db.prepare('SELECT COUNT(*) AS n FROM documents WHERE project_id = ?'),
@@ -204,12 +220,17 @@ class IpsStore {
       // only a document being processed is finished: one requeued or deleted meanwhile isn't
       finish: this.db.prepare("UPDATE documents SET status = ?, status_message = ?, processed_ms = ? WHERE id = ? AND status = 'processing'"),
       // a document being processed is left alone: its pipeline would finish it over the requeue
-      requeue: this.db.prepare("UPDATE documents SET status = 'submitted', status_message = NULL, processed_ms = NULL, analysed_json = NULL WHERE id = ? AND project_id = ? AND status <> 'processing'"),
+      requeue: this.db.prepare("UPDATE documents SET status = 'submitted', status_message = NULL, processed_ms = NULL, analysed_json = NULL, nationality = NULL WHERE id = ? AND project_id = ? AND status <> 'processing'"),
       saveResult: this.db.prepare('INSERT OR REPLACE INTO document_results (doc_id, step, made_ms, json) VALUES (?, ?, ?, ?)'),
       readResult: this.db.prepare('SELECT made_ms, json FROM document_results WHERE doc_id = ? AND step = ?'),
       resultSteps: this.db.prepare('SELECT step, made_ms FROM document_results WHERE doc_id = ? ORDER BY step'),
       clearResults: this.db.prepare('DELETE FROM document_results WHERE doc_id = ?'),
-      resetProcessing: this.db.prepare("UPDATE documents SET status = 'submitted' WHERE status = 'processing'")
+      resetProcessing: this.db.prepare("UPDATE documents SET status = 'submitted' WHERE status = 'processing'"),
+      startRun: this.db.prepare("INSERT INTO pipeline_runs (doc_id, started_ms, outcome) VALUES (?, ?, 'running')"),
+      // the run ends whether or not the document is still there to take the outcome
+      endRun: this.db.prepare("UPDATE pipeline_runs SET outcome = ?, ended_ms = ? WHERE doc_id = ? AND outcome = 'running'"),
+      interruptRuns: this.db.prepare("UPDATE pipeline_runs SET outcome = 'interrupted', ended_ms = ? WHERE outcome = 'running'"),
+      countRuns: this.db.prepare('SELECT outcome, COUNT(*) AS n FROM pipeline_runs WHERE started_ms > ? AND started_ms <= ? GROUP BY outcome')
     };
   }
 
@@ -219,9 +240,15 @@ class IpsStore {
     if (!has('documents', 'analysed_json')) {
       this.db.exec('ALTER TABLE documents ADD COLUMN analysed_json TEXT');
     }
+    if (!has('documents', 'nationality')) {
+      this.db.exec('ALTER TABLE documents ADD COLUMN nationality TEXT');
+    }
     if (!has('national_profiles', 'jurisdiction')) {
       this.db.exec('ALTER TABLE national_profiles ADD COLUMN jurisdiction TEXT');
     }
+    if (!has('national_profiles', 'snomed_edition')) {
+      this.db.exec('ALTER TABLE national_profiles ADD COLUMN snomed_edition TEXT');
+    }
     if (!has('projects', 'ai_json')) {
       // the project's AI assessment settings (JSON; the API key encrypted)
       this.db.exec('ALTER TABLE projects ADD COLUMN ai_json TEXT');
@@ -282,15 +309,15 @@ class IpsStore {
 
   // ---- national profiles ----
 
-  /** All the national profiles: {id, jurisdiction, packageId, version, url, updated_ms}, by package id and version. */
+  /** All the national profiles: {id, jurisdiction, packageId, version, url, snomedEdition, updated_ms}, by package id and version. */
   nationalProfiles() {
-    return this.db.prepare('SELECT id, package_id, version, url, jurisdiction, updated_ms FROM national_profiles ORDER BY package_id, version, id').all()
+    return this.db.prepare('SELECT id, package_id, version, url, jurisdiction, snomed_edition, updated_ms FROM national_profiles ORDER BY package_id, version, id').all()
       .map(nationalProfileOf);
   }
 
-  /** @returns {Object|null} {id, jurisdiction, packageId, version, url, updated_ms} */
+  /** @returns {Object|null} {id, jurisdiction, packageId, version, url, snomedEdition, updated_ms} */
   nationalProfile(id) {
-    const r = this.db.prepare('SELECT id, package_id, version, url, jurisdiction, updated_ms FROM national_profiles WHERE id = ?').get(id);
+    const r = this.db.prepare('SELECT id, package_id, version, url, jurisdiction, snomed_edition, updated_ms FROM national_profiles WHERE id = ?').get(id);
     return r ? nationalProfileOf(r) : null;
   }
 
@@ -301,15 +328,15 @@ class IpsStore {
   }
 
   /** @returns {number} the new national profile's id */
-  createNationalProfile(packageId, version, url, jurisdiction, nowMs = Date.now()) {
-    return Number(this.db.prepare('INSERT INTO national_profiles (package_id, version, url, jurisdiction, updated_ms) VALUES (?, ?, ?, ?, ?)')
-      .run(packageId, version, url, jurisdiction || null, nowMs).lastInsertRowid);
+  createNationalProfile(packageId, version, url, jurisdiction, snomedEdition = null, nowMs = Date.now()) {
+    return Number(this.db.prepare('INSERT INTO national_profiles (package_id, version, url, jurisdiction, snomed_edition, updated_ms) VALUES (?, ?, ?, ?, ?, ?)')
+      .run(packageId, version, url, jurisdiction || null, snomedEdition || null, nowMs).lastInsertRowid);
   }
 
   /** @returns {boolean} whether there was such a national profile */
-  updateNationalProfile(id, packageId, version, url, jurisdiction, nowMs = Date.now()) {
-    return this.db.prepare('UPDATE national_profiles SET package_id = ?, version = ?, url = ?, jurisdiction = ?, updated_ms = ? WHERE id = ?')
-      .run(packageId, version, url, jurisdiction || null, nowMs, id).changes > 0;
+  updateNationalProfile(id, packageId, version, url, jurisdiction, snomedEdition = null, nowMs = Date.now()) {
+    return this.db.prepare('UPDATE national_profiles SET package_id = ?, version = ?, url = ?, jurisdiction = ?, snomed_edition = ?, updated_ms = ? WHERE id = ?')
+      .run(packageId, version, url, jurisdiction || null, snomedEdition || null, nowMs, id).changes > 0;
   }
 
   deleteNationalProfile(id) {
@@ -579,7 +606,7 @@ class IpsStore {
       return { total, rows: [] };
     }
     if (!options.withJson) {
-      const cols = 'd.id, d.received, d.source, d.status, d.status_message, d.size, d.patient_name, d.patient_gender, d.patient_birth, d.comp_date, d.comp_title';
+      const cols = 'd.id, d.received, d.source, d.status, d.status_message, d.size, d.patient_name, d.patient_gender, d.patient_birth, d.comp_date, d.comp_title, d.nationality';
       const rows = this.db.prepare(`SELECT ${cols} FROM documents d ${w} ORDER BY ${search.orderBy} LIMIT ? OFFSET ?`)
         .all(...args, ...search.orderArgs, search.count, search.offset);
       return { total, rows, truncated: false };
@@ -612,19 +639,41 @@ class IpsStore {
    * Take the oldest submitted document for processing, marking it 'processing'.
    * @returns {Object|null} the row (as read()) or null if nothing is waiting
    */
-  claimNext() {
+  claimNext(nowMs = Date.now()) {
     return this.db.transaction(() => {
       const next = this.stmts.nextSubmitted.get();
       if (!next || this.stmts.claim.run(next.id).changes === 0) {
         return null;
       }
+      this.stmts.startRun.run(next.id, nowMs);
       return this.read(next.id);
     })();
   }
 
-  /** Record the outcome of processing a document. */
-  finish(id, ok, message) {
-    this.stmts.finish.run(ok ? 'processed' : 'error', message || null, Date.now(), id);
+  /**
+   * Record the outcome of processing a document: ok, the pipeline finished (the document
+   * is processed); not ok, it failed (the document is in error).
+   */
+  finish(id, ok, message, nowMs = Date.now()) {
+    this.db.transaction(() => {
+      this.stmts.finish.run(ok ? 'processed' : 'error', message || null, nowMs, id);
+      this.stmts.endRun.run(ok ? 'finished' : 'failed', nowMs, id);
+    })();
+  }
+
+  /**
+   * The pipeline runs started in (sinceMs, nowMs], by how they ended.
+   * @returns {{started: number, finished: number, failed: number, interrupted: number, running: number}}
+   */
+  countRuns(sinceMs, nowMs) {
+    const out = { started: 0, finished: 0, failed: 0, interrupted: 0, running: 0 };
+    for (const r of this.stmts.countRuns.all(sinceMs, nowMs)) {
+      if (Object.prototype.hasOwnProperty.call(out, r.outcome)) {
+        out[r.outcome] = r.n;
+      }
+      out.started += r.n;
+    }
+    return out;
   }
 
   /**
@@ -676,6 +725,11 @@ class IpsStore {
     this.stmts.clearResults.run(docId);
   }
 
+  /** The nation a document is from (an ISO 3166 code), or null: the nationality step's answer, for the list. */
+  setNationality(docId, jurisdiction) {
+    this.db.prepare('UPDATE documents SET nationality = ? WHERE id = ?').run(jurisdiction || null, docId);
+  }
+
   /** The steps that have results for a document. */
   resultSteps(docId) {
     return this.stmts.resultSteps.all(docId).map(r => r.step);
@@ -683,10 +737,13 @@ class IpsStore {
 
   /**
    * Anything left 'processing' was being worked on when the server stopped; it goes back
-   * in the queue. Called at startup. @returns {number} how many
+   * in the queue, and its pipeline run was interrupted. Called at startup. @returns {number} how many
    */
-  resetProcessing() {
-    return this.stmts.resetProcessing.run().changes;
+  resetProcessing(nowMs = Date.now()) {
+    return this.db.transaction(() => {
+      this.stmts.interruptRuns.run(nowMs);
+      return this.stmts.resetProcessing.run().changes;
+    })();
   }
 
   /** How many documents are in each state, for the dashboard. */

package/ips/structure.js

@@ -0,0 +1,247 @@
+//
+// Copyright 2026, Health Intersections Pty Ltd (http://www.healthintersections.com.au)
+//
+// Licensed under BSD-3: https://opensource.org/license/bsd-3-clause
+//
+
+/**
+ * The logical structure of an IPS document, as a tree: the Composition, then what it
+ * refers to (other than its sections), then the sections, nested, each with what it refers
+ * to (entries, author, focus...). Each resource referred to holds what it refers to in turn.
+ * A resource is expanded once, at the shallowest place it is met (breadth first, so that one
+ * referred to directly by the Composition is expanded there, not inside the collapsed subject
+ * that also refers to it); everywhere else it is a 'seen' node, which says where it is. A
+ * reference that doesn't resolve in the document is a 'missing' node. References resolve as
+ * in a Bundle (fullUrl, absolute or relative to the referring entry's), and #id is a
+ * resource contained in the referring resource (or in the resource it is contained in).
+ *
+ * The structure view (render.js) draws the tree as a tree table; the analysis step and view
+ * (analysis.js) walk the same tree.
+ *
+ * @module ips/structure
+ */
+
+const escape = require('escape-html');
+const { dateText, describeResource, codeText, quantityText } = require('./presenter');
+const { inBundle } = require('./fhirpath-ips');
+
+function text(v) {
+  return typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' ? String(v) : '';
+}
+
+function isObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * The references in a resource or a part of one, in document order, as [path, reference]:
+ * every Reference with a .reference, at any depth, except under the keys skipped (the
+ * Composition's sections, which are shown as sections) and contained resources (shown
+ * when something refers to them).
+ */
+function referencesIn(node, skip = [], path = '', out = []) {
+  if (Array.isArray(node)) {
+    node.forEach((v, i) => referencesIn(v, [], `${path}[${i}]`, out));
+  } else if (isObject(node)) {
+    if (typeof node.reference === 'string') {
+      out.push([path, node.reference]);
+    }
+    for (const [k, v] of Object.entries(node)) {
+      if (k !== 'contained' && k !== 'text' && !skip.includes(k) && v !== null && typeof v === 'object') {
+        referencesIn(v, [], path ? `${path}.${k}` : k, out);
+      }
+    }
+  }
+  return out;
+}
+
+// the icon for a resource, by type
+const ICONS = {
+  person: ['Patient', 'Practitioner', 'PractitionerRole', 'RelatedPerson', 'Person'],
+  organization: ['Organization'],
+  medication: ['Medication', 'MedicationStatement', 'MedicationRequest', 'MedicationAdministration', 'MedicationDispense', 'MedicationUsage', 'MedicationKnowledge'],
+  audit: ['Provenance', 'AuditEvent'],
+  clinical: ['AllergyIntolerance', 'Condition', 'Observation', 'Procedure', 'Immunization', 'ImmunizationRecommendation', 'DiagnosticReport',
+    'DeviceUseStatement', 'DeviceUsage', 'CarePlan', 'ClinicalImpression', 'Flag', 'Consent', 'Encounter', 'ImagingStudy', 'Specimen',
+    'FamilyMemberHistory', 'RiskAssessment', 'Goal', 'ServiceRequest', 'NutritionOrder', 'DocumentReference', 'QuestionnaireResponse']
+};
+
+function iconOf(type) {
+  return Object.keys(ICONS).find(k => ICONS[k].includes(type)) || 'other';
+}
+
+/**
+ * What a resource is: a name (a person's, an organization's...), else its code (code,
+ * medication, vaccineCode...), with an Observation's value. HTML, escaped.
+ */
+function whatOf(r) {
+  let what = describeResource(r) || codeText(r.medicationCodeableConcept) || codeText(r.medication?.concept) ||
+    (text(r.medicationReference?.display) ? escape(r.medicationReference.display) : '') ||
+    codeText(r.medication?.reference ? null : r.medication) ||
+    (Array.isArray(r.type) ? codeText(r.type[0]) : codeText(r.type)) || codeText(r.activity) ||
+    (Array.isArray(r.category) ? codeText(r.category[0]) : codeText(r.category));
+  if (r.resourceType === 'Observation') {
+    const value = quantityText(r.valueQuantity) || codeText(r.valueCodeableConcept) ||
+      (text(r.valueString) ? escape(r.valueString) : '') || (typeof r.valueBoolean === 'boolean' ? String(r.valueBoolean) : '');
+    if (value) {
+      what = what ? `${what}: ${value}` : value;
+    }
+  }
+  return what || '';
+}
+
+// where to look for when a resource happened, best first: the clinical dates, then the
+// record's own
+const WHEN_PATHS = [
+  'onsetDateTime', 'onsetPeriod.start', 'occurrenceDateTime', 'occurrencePeriod.start', 'performedDateTime', 'performedPeriod.start',
+  'effectiveDateTime', 'effectiveInstant', 'effectivePeriod.start', 'timingDateTime', 'timingPeriod.start', 'whenHandedOver', 'whenPrepared',
+  'authoredOn', 'period.start', 'actualPeriod.start', 'dateTime', 'birthDate', 'recordedDate', 'recorded', 'occurredDateTime',
+  'issued', 'dateAsserted', 'recordedOn', 'created', 'date', 'meta.lastUpdated'
+];
+
+/** When a resource happened: a good try, not a rule. HTML, escaped. */
+function whenOf(r) {
+  for (const p of WHEN_PATHS) {
+    const v = p.split('.').reduce((o, k) => (isObject(o) ? o[k] : undefined), r);
+    if (text(v)) {
+      return dateText(v);
+    }
+  }
+  return '';
+}
+
+/**
+ * The document as a tree. Each node is
+ *   { kind: 'root'|'section'|'resource'|'seen'|'missing', key, path, fullPath, icon, type, id,
+ *     ref, what, when, note, open, children, resource?, section?, entry?, container?, shownAt? }
+ * - shownAt (seen nodes) is the fullPath of the node where the resource is expanded
+ * - path is where the node is in what contains it (subject, entry[0], section[1]); fullPath
+ *   is the whole of it as FHIRPath from the Composition (Composition.section[0].entry[0].resolve().subject)
+ * - key identifies what the node is about, the same each time the tree is made: e{n} for
+ *   bundle entry n, e{n}#id for a resource contained in it, s:{fullPath} for a section
+ * - resource is the resource (resource and seen nodes, and the root), section the section;
+ *   entry is {key, resource, fullUrl, container} - where references in it resolve from
+ * - authors (sections) are the authors that apply to the section: its own, else those of
+ *   what contains it; parentAuthors are those of what contains it
+ *
+ * @returns {Object|null} the root, or null when the document has no Composition
+ */
+function structureTree(bundle) {
+  const entries = Array.isArray(bundle?.entry) ? bundle.entry : [];
+  const comp = entries[0]?.resource;
+  if (!isObject(comp) || comp.resourceType !== 'Composition') {
+    return null;
+  }
+  const shown = new Map([['e0', 'Composition']]); // key -> fullPath of the node that expands it
+
+  function resolve(from, ref) {
+    if (ref.startsWith('#')) {
+      const host = from.container || from;
+      if (ref === '#') {
+        return host;
+      }
+      const list = Array.isArray(host.resource.contained) ? host.resource.contained : [];
+      const i = list.findIndex(c => isObject(c) && c.id === ref.substring(1));
+      return i < 0 ? null : { key: `${host.key}#${ref.substring(1)}`, resource: list[i], fullUrl: host.fullUrl, container: host };
+    }
+    const found = inBundle(bundle, ref, from.fullUrl);
+    return found ? { key: `e${found.index}`, resource: found.resource, fullUrl: entries[found.index].fullUrl } : null;
+  }
+
+  const resourceNode = (path, fullPath, entry, extra = {}) => {
+    const r = entry.resource;
+    return {
+      kind: 'resource', key: entry.key, path, fullPath, icon: iconOf(r.resourceType), type: r.resourceType || '?', id: text(r.id) ? r.id : '',
+      what: whatOf(r), when: whenOf(r), note: '', children: [], resource: r, entry, ...extra
+    };
+  };
+
+  // The reference nodes are made breadth first: refNodes returns an array with a slot for
+  // each reference, and the slots are filled in when the queue gets to them, shallowest
+  // first (in the order met, at the same depth). So which node gets to expand a resource
+  // depends on how deep it is, not on whether some earlier reference's subtree reached it first.
+  const queue = [];
+  function refNodes(from, refs, base, depth) {
+    const slots = refs.map(() => null);
+    queue.push({ from, refs, base, depth, slots });
+    return slots;
+  }
+
+  function makeRefNodes({ from, refs, base, depth, slots }) {
+    refs.forEach(([path, ref], i) => {
+      const fullPath = `${base}.${path}`;
+      const target = resolve(from, ref);
+      if (!target) {
+        const m = /(?:^|\/)([A-Z][A-Za-z]+)\/([^/]+?)(?:\/_history\/[^/]+)?$/.exec(ref);
+        slots[i] = { kind: 'missing', key: null, path, fullPath, icon: 'external', type: m ? m[1] : '', id: m ? m[2] : '', ref, what: '', when: '', note: 'not in document', children: [] };
+        return;
+      }
+      const contained = target.container ? 'contained' : '';
+      if (shown.has(target.key)) {
+        const shownAt = shown.get(target.key);
+        slots[i] = resourceNode(path, fullPath, target, { kind: 'seen', ref, shownAt, note: [contained, `shown at ${shownAt}`].filter(Boolean).join(', ') });
+        return;
+      }
+      shown.set(target.key, fullPath);
+      const node = resourceNode(path, fullPath, target, { ref, note: contained });
+      // a medication statement, request... by reference: what it is is the Medication's
+      const med = target.resource.medicationReference?.reference || target.resource.medication?.reference?.reference;
+      if (!node.what && typeof med === 'string') {
+        const m = resolve(target, med);
+        node.what = m ? whatOf(m.resource) : '';
+      }
+      node.children = refNodes(target, referencesIn(target.resource), `${fullPath}.resolve()`, depth + 1);
+      slots[i] = node;
+    });
+  }
+
+  function runQueue() {
+    while (queue.length > 0) {
+      let next = 0;
+      for (let i = 1; i < queue.length; i++) {
+        if (queue[i].depth < queue[next].depth) {
+          next = i;
+        }
+      }
+      makeRefNodes(queue.splice(next, 1)[0]);
+    }
+  }
+
+  const rootEntry = { key: 'e0', resource: comp, fullUrl: entries[0].fullUrl };
+  const authorsOf = (x) => (Array.isArray(x?.author) ? x.author.filter(isObject) : []);
+  function sectionNodes(list, base, prefix, parentAuthors, depth) {
+    return (Array.isArray(list) ? list : []).map((sec, i) => [sec, i]).filter(([sec]) => isObject(sec)).map(([sec, i]) => {
+      const path = `${prefix}section[${i}]`;
+      const fullPath = `Composition.${path}`;
+      const title = text(sec.title) ? sec.title : text(sec.code?.text) ? sec.code.text :
+        (Array.isArray(sec.code?.coding) && sec.code.coding.find(c => text(c?.display))?.display) || '(untitled section)';
+      const authors = authorsOf(sec).length ? authorsOf(sec) : parentAuthors;
+      // the reference slots first (filled in by the queue), then the subsections
+      const children = refNodes(rootEntry, referencesIn(sec, ['section']), fullPath, depth + 1);
+      children.push(...sectionNodes(sec.section, fullPath, `${path}.`, authors, depth + 1));
+      return {
+        kind: 'section', key: `s:${fullPath}`, path, fullPath, icon: 'section', type: 'Section', id: '', what: `<b>${escape(title)}</b>`, when: '',
+        note: children.length ? '' : 'empty', open: true, children, section: sec, entry: rootEntry, authors, parentAuthors, nested: base !== 'Composition'
+      };
+    });
+  }
+  const top = { ...resourceNode('Composition', 'Composition', rootEntry, { open: true }), kind: 'root' };
+  top.what = text(comp.title) ? escape(comp.title) : top.what;
+  top.icon = 'document';
+  top.children = refNodes(rootEntry, referencesIn(comp, ['section']), 'Composition', 1);
+  top.children.push(...sectionNodes(comp.section, 'Composition', '', authorsOf(comp), 1));
+  runQueue();
+  top.resolve = resolve;
+  return top;
+}
+
+/** The nodes of a tree, depth first, as [node, depth, parent]. */
+function flatten(node, depth = 0, parent = null, out = []) {
+  out.push([node, depth, parent]);
+  for (const c of node.children) {
+    flatten(c, depth + 1, node, out);
+  }
+  return out;
+}
+
+module.exports = { structureTree, flatten, referencesIn, whatOf, whenOf, iconOf, isObject, text };

package/ips/terminology.js

@@ -391,5 +391,5 @@ function terminologyOf(bundle) {
 
 module.exports = {
   terminologyOf, conceptsOf, systemName, describeVersion, sctEdition, linkForSystem, linkForCode, isExternalSystem, isIgnored,
-  sectionRank, SECTION_ORDER, IGNORED, SYSTEM_NAMES
+  sectionRank, SECTION_ORDER, IGNORED, SYSTEM_NAMES, typeOf
 };

package/library/body-limit.js

@@ -0,0 +1,22 @@
+/**
+ * The largest request body the server's body parsers accept, from server.maxBodyMB
+ * (megabytes; default 50). A body is read whole into memory before it is parsed, so this
+ * bounds the memory one request can take. A body over it gets a 413 - an OperationOutcome
+ * on a tx endpoint (see TXModule.setupEndpoint).
+ */
+
+const DEFAULT_MAX_BODY_MB = 50;
+
+/**
+ * @param {Object} serverConfig - the "server" section of config.json
+ * @returns {number} the limit in bytes
+ */
+function maxBodyBytes(serverConfig) {
+  let mb = Number(serverConfig?.maxBodyMB ?? DEFAULT_MAX_BODY_MB);
+  if (!Number.isFinite(mb) || mb <= 0) {
+    mb = DEFAULT_MAX_BODY_MB; // not a usable number: the default, not no limit
+  }
+  return Math.round(mb * 1024 * 1024);
+}
+
+module.exports = { maxBodyBytes, DEFAULT_MAX_BODY_MB };

package/library/cache-generation.js

@@ -0,0 +1,15 @@
+const crypto = require('crypto');
+
+// A random token for the shared resource cache (tx/resource-cache-sqlite.js): 22 FHIR id
+// characters from [A-Za-z0-9-], about 131 random bits. There is no '.' in it, so a cache-id
+// "<code>.<generation>.<random>" splits on '.' into exactly its parts, and the code in front
+// (what a proxy routes on) can't run into a token. With a 16-character code the id is 62
+// characters, inside FHIR's 64.
+const TOKEN = /^[A-Za-z0-9-]{22}$/;
+
+function newCacheGeneration() {
+  // base64url of 17 bytes, cut to 22 characters; '_' (not an id character) becomes '-'
+  return crypto.randomBytes(17).toString('base64url').slice(0, 22).replace(/_/g, '-');
+}
+
+module.exports = { newCacheGeneration, TOKEN };

package/library/cgroup-memory.js

@@ -110,4 +110,136 @@ function readCgroupMemoryLimit(opts = {}) {
   return { limit: 0, source: null };
 }
 
-module.exports = { readCgroupMemoryLimit };
+/**
+ * The directory of this process's own cgroup (memory controller), and whether it is v2 or
+ * v1. null when there is none to be found (not Linux, or no /proc).
+ * @param {Object} [opts] - procFile, cgroupRoot (tests)
+ * @returns {{dir: string, version: 2|1}|null}
+ */
+function ownCgroupDir(opts = {}) {
+  const procFile = opts.procFile || '/proc/self/cgroup';
+  const cgroupRoot = opts.cgroupRoot || '/sys/fs/cgroup';
+  let lines;
+  try {
+    lines = fs.readFileSync(procFile, 'utf8').split('\n').filter(l => l.trim() !== '');
+  } catch {
+    return null;
+  }
+  const v2 = lines.find(l => l.startsWith('0::'));
+  if (v2) {
+    const dir = path.join(cgroupRoot, path.posix.normalize(v2.substring(3) || '/'));
+    if (fs.existsSync(path.join(dir, 'memory.stat'))) {
+      return { dir, version: 2 };
+    }
+  }
+  for (const l of lines) {
+    const parts = l.split(':');
+    if (parts.length >= 3 && parts[1].split(',').includes('memory')) {
+      const dir = path.join(cgroupRoot, 'memory', path.posix.normalize(parts.slice(2).join(':') || '/'));
+      if (fs.existsSync(path.join(dir, 'memory.stat'))) {
+        return { dir, version: 1 };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * What memory.stat says a cgroup holds: its private memory (`anon`: what the kernel can't take
+ * back without killing a process) and its page cache (`file`: the terminology and SQLite files,
+ * mapped or read, which the kernel drops when it needs the room; shared pages counted once).
+ * v2: 'anon' and 'file'; v1: 'total_rss' (else 'rss') and 'total_cache' (else 'cache').
+ * @param {{dir: string, version: 2|1}} cg - from ownCgroupDir
+ * @returns {{anon: number, file: number|null}|null} bytes, or null if it can't be read
+ */
+function readCgroupStat(cg) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(cg.dir, 'memory.stat'), 'utf8');
+  } catch {
+    return null;
+  }
+  const values = new Map();
+  for (const line of text.split('\n')) {
+    const i = line.indexOf(' ');
+    if (i > 0) {
+      values.set(line.substring(0, i), Number(line.substring(i + 1)));
+    }
+  }
+  const first = keys => {
+    for (const key of keys) {
+      const v = values.get(key);
+      if (Number.isFinite(v) && v >= 0) {
+        return v;
+      }
+    }
+    return null;
+  };
+  const v2 = cg.version === 2;
+  const anon = first(v2 ? ['anon'] : ['total_rss', 'rss']);
+  return anon === null ? null : { anon, file: first(v2 ? ['file'] : ['total_cache', 'cache']) };
+}
+
+/**
+ * The private memory of everything in a cgroup (memory.stat 'anon'; see readCgroupStat). The
+ * page cache isn't counted: the kernel drops it when it needs the room.
+ * @param {{dir: string, version: 2|1}} cg - from ownCgroupDir
+ * @returns {number} bytes, or 0 if it can't be read
+ */
+function readCgroupAnon(cg) {
+  const stat = readCgroupStat(cg);
+  return stat ? stat.anon : 0;
+}
+
+/**
+ * A process's resident memory by kind, from /proc/<pid>/status: RssAnon (its private memory)
+ * and RssFile (the file pages it has mapped and touched, such as the SNOMED CT cache files;
+ * pages shared with other processes are counted in each). Linux only.
+ * @param {number|string} pid - or 'self'
+ * @param {string} [procRoot='/proc'] - (tests)
+ * @returns {{anon: number, file: number}|null} bytes, or null if it can't be read
+ */
+function readProcessMemory(pid, procRoot = '/proc') {
+  let status;
+  try {
+    status = fs.readFileSync(path.join(procRoot, String(pid), 'status'), 'utf8');
+  } catch {
+    return null;
+  }
+  const kb = name => {
+    const m = new RegExp(`^${name}:\\s+(\\d+) kB`, 'm').exec(status);
+    return m ? Number(m[1]) * 1024 : null;
+  };
+  const anon = kb('RssAnon');
+  return anon === null ? null : { anon, file: kb('RssFile') ?? 0 };
+}
+
+/**
+ * The RSS of each process in a cgroup, from /proc/<pid>/status. Processes that have gone,
+ * or can't be read, are left out.
+ * @param {{dir: string}} cg - from ownCgroupDir
+ * @returns {Map<number, number>} pid -> bytes
+ */
+function readCgroupProcessRss(cg) {
+  const result = new Map();
+  let pids;
+  try {
+    pids = fs.readFileSync(path.join(cg.dir, 'cgroup.procs'), 'utf8').split('\n').filter(Boolean).map(Number);
+  } catch {
+    return result;
+  }
+  for (const pid of pids) {
+    try {
+      const status = fs.readFileSync(`/proc/${pid}/status`, 'utf8');
+      const m = /^VmRSS:\s+(\d+) kB/m.exec(status);
+      if (m) {
+        result.set(pid, Number(m[1]) * 1024);
+      }
+    } catch {
+      // gone
+    }
+  }
+  return result;
+}
+
+module.exports = { readCgroupMemoryLimit, ownCgroupDir, readCgroupStat, readCgroupAnon, readProcessMemory, readCgroupProcessRss };