@heroiclands/package-build 25.5.4 → 25.6.0

package/engine/site-serve.mjs

@@ -25,21 +25,20 @@
  *
  * A page that changes because another note changed — a table that lists the
  * note, a link that carries its name — is written again by the next whole
- * build. A note in error is written as its page shows it, and the error is
- * reported; a build whose gates fire writes nothing and leaves the last good
- * site in place.
+ * build. A failed build is reported and leaves the last successful site in
+ * place, including its search index.
  *
  * The site is served from the deployed root, so a page is at the address it is
  * deployed at, its base path included. Every HTML page is sent with a script
  * that listens on {@link RELOAD_PATH} for the server's `reload` event; the
  * script is added as the page is sent and is never written to the site. The
- * search index is built once, after the first build.
+ * search index is built with each whole build before it replaces the last site.
  *
  * @module
  */
 
 import fs from "node:fs";
-import http from "node:http";
+import { Worker } from "node:worker_threads";
 import path from "node:path";
 
 import { siteBuildFailed } from "./site-build.mjs";
@@ -47,6 +46,7 @@ import { SITE_THEME_DIR } from "./site-theme.mjs";
 import { SITE_STATIC_DIR, buildPackageSite, writeSite, writeThemeFiles } from "./site-render.mjs";
 import { siteBase } from "../content-config.mjs";
 import { SEARCH_DIR, indexSite } from "./site-root.mjs";
+import { readCachedNavigation, siteSettings } from "./site-config.mjs";
 
 /** The address a served page listens on for the server's reloads. */
 export const RELOAD_PATH = "/__package-build/reload";
@@ -54,29 +54,6 @@ export const RELOAD_PATH = "/__package-build/reload";
 /** How long a burst of changes is gathered before it is written, in milliseconds. */
 const SETTLE_MS = 120;
 
-/** What a file is sent as, by its extension. */
-const CONTENT_TYPES = Object.freeze({
-    ".html": "text/html; charset=utf-8",
-    ".css": "text/css; charset=utf-8",
-    ".js": "text/javascript; charset=utf-8",
-    ".mjs": "text/javascript; charset=utf-8",
-    ".json": "application/json",
-    ".xml": "application/xml",
-    ".txt": "text/plain; charset=utf-8",
-    ".svg": "image/svg+xml",
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".webp": "image/webp",
-    ".gif": "image/gif",
-    ".woff2": "font/woff2",
-    ".woff": "font/woff",
-    ".wasm": "application/wasm",
-});
-
-/** The script a served page is sent with. */
-const RELOAD_SCRIPT = `<script>new EventSource(${JSON.stringify(RELOAD_PATH)}).addEventListener("reload", () => location.reload());</script>`;
-
 /** Whether a note's text holds a query its build prepares ahead of the render. */
 const holdsQuery = (text) => /```\s*sql\b|\{\{[^}]*\bsql\b/.test(text);
 
@@ -91,16 +68,19 @@ const holdsQuery = (text) => /```\s*sql\b|\{\{[^}]*\bsql\b/.test(text);
  *   directory above `out` by default; `out` itself for a site served at `/`.
  * @param {string} [options.host] - The address to listen on.
  * @param {number} [options.port] - The port; `0` takes any free one.
- * @param {boolean} [options.search] - Build the search index after the first
+ * @param {boolean} [options.search] - Build the search index with each whole
  *   build, where the site has one.
  * @param {number} [options.year] - The year the footer states.
- * @param {(event: {kind: string, built?: object, files?: string[], findings?: object[], error?: unknown}) => void} [options.report] -
- *   Told of each build: `built` for a whole build, `page` for one note's page,
+ * @param {(event: {kind: string, built?: object, files?: string[], findings?: object[], error?: unknown, message?: string, fatal?: boolean}) => void} [options.report] -
+ *   Told of progress (`message`) and each build: `built` for a whole build, `page` for one note's page,
  *   `theme` for the theme, `failed` with what the build found, `error` with
  *   what it threw.
- * @returns {Promise<{url: string, close: () => Promise<void>, settled: () => Promise<void>}>}
- *   The address of the site's home page, how to stop serving, and a promise
- *   for the moment every change seen so far has been written.
+ * @returns {Promise<{url: string, close: () => Promise<void>, settled: () => Promise<void>, done: Promise<void>}>}
+ *   Resolves as soon as HTTP listens, before the first build. The address of
+ *   the site's home page, how to stop serving, and a promise for the initial
+ *   build and every change seen so far to finish. Failed builds are reported
+ *   through `report` and leave the last successful site in service. `done`
+ *   resolves on close and rejects if HTTP stops unexpectedly.
  */
 export async function serveSite({
     config,
@@ -112,27 +92,147 @@ export async function serveSite({
     year,
     report = () => {},
 }) {
-    /** @type {Set<http.ServerResponse>} */
-    const listeners = new Set();
+    // Refuse a site that cannot be described before starting its server.
+    siteSettings({ config });
+    readCachedNavigation(config);
+    root = path.resolve(root);
+    out = path.resolve(out);
+    let timer = null;
+    const watchers = [];
+    let closing = false;
+    let complete;
+    let abort;
+    const done = new Promise((resolve, reject) => {
+        complete = resolve;
+        abort = reject;
+    });
+    // The caller may attach its lifecycle handler after awaiting startup.
+    done.catch(() => {});
+    const stopWatching = () => {
+        if (timer) clearTimeout(timer);
+        timer = null;
+        for (const watcher of watchers) watcher.close();
+    };
+    const worker = new Worker(new URL("./site-serve-http.mjs", import.meta.url), {
+        workerData: { root, out, host, port, reloadPath: RELOAD_PATH },
+        // The HTTP helper uses only Node builtins. A caller's --input-type
+        // or loader flags describe its own entry point, not this file.
+        execArgv: [],
+    });
+    let workerFailure;
+    let started = false;
+    const requests = new Map();
+    worker.on("message", (event) => {
+        const waiting = requests.get(event.kind);
+        if (!waiting) return;
+        requests.delete(event.kind);
+        if (event.error) waiting.reject(event.error);
+        else waiting.resolve(event);
+    });
+    const failed = (error) => {
+        if (workerFailure) return;
+        workerFailure = error;
+        stopWatching();
+        abort(error);
+        for (const waiting of requests.values()) waiting.reject(error);
+        requests.clear();
+        if (started) report({ kind: "error", error, fatal: true });
+    };
+    worker.on("error", failed);
+    const exited = new Promise((resolve) => {
+        worker.once("exit", (code) => {
+            if ((started || requests.size) && !workerFailure)
+                failed(new Error(`the preview HTTP server stopped (exit ${code})`));
+            resolve();
+        });
+    });
+    const receive = (kind) =>
+        new Promise((resolve, reject) => {
+            if (workerFailure) reject(workerFailure);
+            else requests.set(kind, { resolve, reject });
+        });
+    const listening = await receive("listening");
+    started = true;
     let state = null;
+    const progress = (message) => report({ kind: "progress", message });
+    const reload = () => worker.postMessage({ kind: "reload" });
 
-    const reload = () => {
-        for (const res of listeners) res.write("event: reload\ndata: {}\n\n");
+    // Whole builds and incremental updates publish through the same boundary.
+    // HTTP owns the renames, between requests; writers only touch private trees.
+    const publish = async (write) => {
+        if (workerFailure || closing) return null;
+        fs.mkdirSync(path.dirname(out), { recursive: true });
+        const staging = fs.mkdtempSync(path.join(path.dirname(out), ".site-preview-"));
+        const staged = path.join(staging, "site");
+        const previous = path.join(staging, "previous");
+        let installed = false;
+        try {
+            const result = await write(staged);
+            if (!result || closing) return null;
+            if (workerFailure) throw workerFailure;
+            const ready = receive("installed");
+            worker.postMessage({ kind: "install", staged, previous });
+            await ready;
+            installed = true;
+            return result;
+        } finally {
+            // A failed rollback must retain the only remaining previous tree.
+            if (installed || !fs.existsSync(previous))
+                fs.rmSync(staging, { recursive: true, force: true });
+        }
     };
 
     const buildAll = async () => {
-        const result = await buildPackageSite({ config, out, year });
-        if (!result.written || siteBuildFailed(result.built))
-            report({ kind: "failed", built: result.built });
-        if (!result.written) return false;
+        const result = await publish(async (staged) => {
+            const built = await buildPackageSite({ config, out: staged, year, progress });
+            const findings = [...(built.written?.findings ?? []), ...(built.fonts?.findings ?? [])];
+            if (
+                !built.written ||
+                siteBuildFailed(built.built) ||
+                built.fonts?.findings.length ||
+                findings.some((finding) => finding.severity === "error")
+            ) {
+                report({ kind: "failed", built: built.built, findings });
+                return null;
+            }
+            if (search && config.site.search !== false) {
+                progress("building the search index");
+                const indexed = await indexSite({
+                    site: staged,
+                    output: path.join(staged, SEARCH_DIR),
+                    base: siteBase(config),
+                });
+                progress(`indexed ${indexed.pages} page(s) for search`);
+            }
+            return { ...built, findings };
+        });
+        if (!result) return false;
         state = result;
-        report({ kind: "built", built: result.built, findings: result.written.findings });
+        report({ kind: "built", built: result.built, findings: result.findings });
         return true;
     };
 
-    const redrawNotes = (files) => {
+    const redraw = async ({ pages, only, theme = false }) => {
+        return publish((staged) => {
+            // Keep unchanged pages, static files and the current search index.
+            fs.cpSync(out, staged, { recursive: true, mode: fs.constants.COPYFILE_FICLONE });
+            if (theme) writeThemeFiles(staged);
+            const written = writeSite({ site: state.site, pages, out: staged, only });
+            if (written.findings.some((finding) => finding.severity === "error")) {
+                report({ kind: "failed", findings: written.findings });
+                return null;
+            }
+            return {
+                ...written,
+                files: written.files.map((file) => path.join(out, path.relative(staged, file))),
+            };
+        });
+    };
+
+    const redrawNotes = async (files) => {
         if (!state) return false;
         const changed = new Set();
+        let pages = state.pages;
         for (const file of files) {
             const text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
             if (!file.endsWith(".md") || !text || holdsQuery(text)) return false;
@@ -140,41 +240,33 @@ export async function serveSite({
             if (!entry) return false;
             if (entry.findings.length) {
                 report({ kind: "failed", findings: entry.findings });
-                return true;
+                return null;
             }
             const page = state.pageOf(entry);
-            state.pages = state.pages.map((old) => (old.url === page.url ? page : old));
+            pages = pages.map((old) => (old.url === page.url ? page : old));
             changed.add(page.url);
         }
-        const written = writeSite({ site: state.site, pages: state.pages, out, only: changed });
+        const written = await redraw({ pages, only: changed });
+        if (!written) return null;
+        state.pages = pages;
         report({ kind: "page", files: written.files, findings: written.findings });
         return true;
     };
 
-    const redrawTheme = () => {
+    const redrawTheme = async () => {
         if (!state) return false;
-        writeThemeFiles(out);
-        const written = writeSite({
-            site: state.site,
+        const written = await redraw({
             pages: state.pages,
-            out,
             only: new Set(state.pages.map((page) => page.url)),
+            theme: true,
         });
+        if (!written) return false;
         report({ kind: "theme", files: written.files, findings: written.findings });
         return true;
     };
 
-    const indexForSearch = async () => {
-        if (!search || config.site.search === false || !state) return;
-        await indexSite({ site: out, output: path.join(out, SEARCH_DIR), base: siteBase(config) });
-    };
-
-    await buildAll();
-    await indexForSearch();
-
     /** @type {{content: Set<string>, theme: boolean}} */
     let pending = { content: new Set(), theme: false };
-    let timer = null;
     let work = Promise.resolve();
     const flush = () => {
         timer = null;
@@ -182,93 +274,71 @@ export async function serveSite({
         pending = { content: new Set(), theme: false };
         work = work.then(async () => {
             try {
-                let done = true;
-                if (batch.content.size && !redrawNotes([...batch.content])) {
-                    done = await buildAll();
-                    if (done) await indexForSearch();
-                } else if (batch.theme) done = redrawTheme();
-                if (done) reload();
+                if (workerFailure || closing) return;
+                let changed = batch.content.size ? await redrawNotes([...batch.content]) : true;
+                if (changed === false) changed = await buildAll();
+                else if (changed && batch.theme) changed = await redrawTheme();
+                if (changed) reload();
             } catch (error) {
-                report({ kind: "error", error });
+                if (error !== workerFailure) report({ kind: "error", error });
             }
         });
     };
     const queue = (kind, file) => {
+        if (workerFailure || closing) return;
         if (kind === "theme") pending.theme = true;
         else pending.content.add(file);
         if (!timer) timer = setTimeout(flush, SETTLE_MS);
     };
 
-    const watchers = [
-        fs.watch(config.paths.content, { recursive: true }, (_event, name) => {
-            if (name) queue("content", path.join(config.paths.content, String(name)));
-        }),
-        ...[SITE_THEME_DIR, SITE_STATIC_DIR]
-            .filter((dir) => fs.existsSync(dir))
-            .map((dir) => fs.watch(dir, { recursive: true }, () => queue("theme"))),
-    ];
-
-    const server = http.createServer((req, res) => {
-        const address = decodeURIComponent(
-            new URL(req.url ?? "/", "http://serve.invalid").pathname,
+    try {
+        watchers.push(
+            fs.watch(config.paths.content, { recursive: true }, (_event, name) => {
+                if (name) queue("content", path.join(config.paths.content, String(name)));
+            }),
         );
-        if (address === RELOAD_PATH) {
-            res.writeHead(200, {
-                "content-type": "text/event-stream",
-                "cache-control": "no-cache",
-                connection: "keep-alive",
-            });
-            res.write(": connected\n\n");
-            listeners.add(res);
-            req.on("close", () => listeners.delete(res));
-            return;
+        for (const dir of [SITE_THEME_DIR, SITE_STATIC_DIR]) {
+            if (fs.existsSync(dir))
+                watchers.push(fs.watch(dir, { recursive: true }, () => queue("theme")));
         }
-        let file = path.join(root, address);
-        if (!file.startsWith(root)) {
-            res.writeHead(403).end();
-            return;
-        }
-        if (fs.statSync(file, { throwIfNoEntry: false })?.isDirectory())
-            file = path.join(file, "index.html");
-        let status = 200;
-        if (!fs.existsSync(file)) {
-            status = 404;
-            file = path.join(out, "404.html");
-            if (!fs.existsSync(file)) {
-                res.writeHead(404).end();
-                return;
-            }
-        }
-        const type = CONTENT_TYPES[path.extname(file).toLowerCase()] ?? "application/octet-stream";
-        let body = fs.readFileSync(file);
-        if (type.startsWith("text/html")) {
-            const html = body.toString("utf8");
-            const at = html.lastIndexOf("</body>");
-            body = Buffer.from(
-                at < 0 ? html + RELOAD_SCRIPT : html.slice(0, at) + RELOAD_SCRIPT + html.slice(at),
-            );
+    } catch (error) {
+        stopWatching();
+        started = false;
+        worker.postMessage({ kind: "close" });
+        await exited;
+        abort(error);
+        throw error;
+    }
+
+    // Return the listening address before beginning the first long build.
+    work = new Promise((resolve) => setImmediate(resolve)).then(async () => {
+        try {
+            if (await buildAll()) reload();
+        } catch (error) {
+            if (error !== workerFailure) report({ kind: "error", error });
         }
-        res.writeHead(status, { "content-type": type, "cache-control": "no-store" });
-        res.end(body);
     });
-    await new Promise((resolve) => server.listen(port, host, resolve));
-    const listening = /** @type {import("node:net").AddressInfo} */ (server.address());
-    const base = new URL(config.homepage).pathname;
 
     return {
-        url: `http://${host}:${listening.port}${base}`,
+        url: `http://${host}:${listening.port}${new URL(config.homepage).pathname}`,
+        done,
         settled: async () => {
-            while (timer || pending.content.size || pending.theme) {
+            for (;;) {
+                const current = work;
+                await current;
+                if (workerFailure) throw workerFailure;
+                if (!timer && !pending.content.size && !pending.theme && current === work) return;
                 await new Promise((resolve) => setTimeout(resolve, SETTLE_MS));
             }
-            await work;
         },
         close: async () => {
-            if (timer) clearTimeout(timer);
-            for (const watcher of watchers) watcher.close();
-            for (const res of listeners) res.end();
+            closing = true;
+            stopWatching();
             await work;
-            await new Promise((resolve) => server.close(() => resolve()));
+            started = false;
+            worker.postMessage({ kind: "close" });
+            await exited;
+            complete();
         },
     };
 }

package/engine/sql-tables.mjs

@@ -217,6 +217,59 @@ export function findSqlBlocks(markdown) {
     return blocks;
 }
 
+/**
+ * Overwrite string literals and comments with spaces, keeping every offset and
+ * newline, so a search of what remains reads only identifiers and operators.
+ *
+ * @param {string} sql - A query.
+ * @returns {string} The query, the same length.
+ */
+function maskLiterals(sql) {
+    const blank = (text) => text.replace(/[^\n]/g, " ");
+    return sql.replace(/'(?:[^']|'')*'|--[^\n]*|\/\*[\s\S]*?\*\//g, blank);
+}
+
+/**
+ * Where a query reads the `file` block of the index record: `file.path`,
+ * `file.folder` or `file.name`, bare or qualified by a relation or its alias.
+ * A note is selected by property, tag or address, so a query that reaches for
+ * the file it was written in is refused. A field of a note's own data that is
+ * named `file` is not the block and is left alone.
+ *
+ * @param {string} sql - One fence's query.
+ * @returns {{line: number, column: number, text: string}|undefined} The first
+ *   reference, its 0-based line within the query and 1-based column, or
+ *   nothing where the query makes none.
+ */
+export function findFileReference(sql) {
+    const masked = maskLiterals(String(sql ?? ""));
+    const qualifiers = new Set();
+    for (const [, relation, alias] of masked.matchAll(
+        /\b(?:from|join)\s+([\w."]+)(?:\s+(?:as\s+)?([A-Za-z_]\w*))?/gi,
+    )) {
+        qualifiers.add(relation.split(".").at(-1).replaceAll('"', ""));
+        if (
+            alias &&
+            !/^(where|group|order|limit|join|inner|left|right|full|cross|on|union|having|window|qualify|using|natural)$/i.test(
+                alias,
+            )
+        )
+            qualifiers.add(alias);
+    }
+    const reference = /(?<![\w$"])(?:(\w+|"\w+")\s*\.\s*)?"?file"?\s*\.\s*"?(path|folder|name)\b/gi;
+    for (const match of masked.matchAll(reference)) {
+        const qualifier = match[1]?.replaceAll('"', "");
+        if (qualifier && !qualifiers.has(qualifier)) continue;
+        const before = masked.slice(0, match.index);
+        return {
+            line: before.split("\n").length - 1,
+            column: match.index - (before.lastIndexOf("\n") + 1) + 1,
+            text: match[0].replace(/\s+/g, ""),
+        };
+    }
+    return undefined;
+}
+
 /** Omit the Foundry export from SQL; the canonical index stays intact.
  * Keep encoding source keys as case-sensitive values in the SQL projection.
  * The canonical index retains its authored mapping object; DuckDB structs
@@ -1371,6 +1424,16 @@ export async function prepareSqlTables(db, sources, { linkable, records, pageLan
         for (const [ordinal, block] of blocks.entries()) {
             try {
                 if (block.problems.length) throw new Error(block.problems.join("; "));
+                const reference = findFileReference(block.query);
+                if (reference) {
+                    forNote.push({
+                        reason: `\`${reference.text}\` is not available to a query; a query selects notes by property, tag or address`,
+                        line: block.line + 1 + reference.line,
+                        column: reference.column,
+                        allowEmpty: block.allowEmpty,
+                    });
+                    continue;
+                }
                 const result = await runSqlQuery(reader, block.query);
                 const options = {
                     linkable,
@@ -1558,11 +1621,13 @@ export async function prepareInlineSqlExpressions(db, sources) {
  * @param {Map<string, Map<string, string>>} [opts.derived] - The derived
  *   lists, from an earlier call over the same records, which are not derived
  *   again.
+ * @param {Map<string,{raw?:string}>} [opts.parsed] - Captured source locators.
  * @param {object[]} [opts.all=records] - Complete records for lexical lineage
  *   traversal through providers outside the surface's audience.
  * @returns {Promise<{sections: Map<string, string>, views: Set<string>,
  *   derived: Map<string, Map<string, string>>,
- *   lexical: Map<string, import("./lexical-sections.mjs").LexicalSection[]>}>} Note file to its sections,
+ *   lexical: Map<string, import("./lexical-sections.mjs").LexicalSection[]>,
+ *   declared: Map<string, Array<{slug:string,heading:string,markdown:string}>>}>} Note file to its sections,
  *   joined in order; the files whose sections hold an event view's fence; and
  *   the derived lists alone.
  */
@@ -1570,7 +1635,7 @@ export async function generatedSectionsFor(
     db,
     records,
     contentBase,
-    { only, foreignIndex, config, derived: given, all = records } = {},
+    { only, foreignIndex, config, derived: given, all = records, parsed } = {},
 ) {
     const notes = records.filter((record) => isNoteRecord(record));
     const fileOf = (record) => noteFile(contentBase, record);
@@ -1583,11 +1648,27 @@ export async function generatedSectionsFor(
             foreignIndex,
             config,
             only,
+            all,
+            rawOf: (file) => parsed?.get(file)?.raw,
         });
     const views = db ? await eventViewSections(db, notes, fileOf, only) : new Map();
     const sections = new Map();
-    for (const file of new Set([...derived.keys(), ...views.keys()]))
-        sections.set(file, joinSections([derived.get(file), views.get(file)]));
+    const declared = new Map();
+    for (const file of new Set([...derived.keys(), ...views.keys()])) {
+        const lists = new Map(derived.get(file));
+        const settlements = lists.get("settlements");
+        if (settlements)
+            declared.set(file, [
+                {
+                    slug: "settlements",
+                    heading: "Settlements",
+                    markdown: settlements.replace(/^# Settlements \{#settlements\}\s*\n/, ""),
+                },
+            ]);
+        lists.delete("settlements");
+        const text = joinSections([lists, views.get(file)]);
+        if (text) sections.set(file, text);
+    }
     // Automatic sections follow their source's audience even in a Foundry
     // corpus containing both public and private packs. Explicit SQL keeps
     // the database audience the caller requested.
@@ -1607,7 +1688,7 @@ export async function generatedSectionsFor(
         if (owners.has(key) && (only === undefined || fileOf(note) === only))
             lexical.set(fileOf(note), owners.get(key));
     }
-    return { sections, views: new Set(views.keys()), derived, lexical };
+    return { sections, views: new Set(views.keys()), derived, lexical, declared };
 }
 
 /**
@@ -1654,11 +1735,16 @@ export function joinGeneratedSections(generated, sources, parsed) {
  * empty set carrying them.
  *
  * @param {Map<string, object[]>} prepared - From {@link prepareSqlTables}.
- * @param {{sections: Map<string, string>, lexical?: Map<string, import("./lexical-sections.mjs").LexicalSection[]>}} generated - From
+ * @param {{sections: Map<string, string>, lexical?: Map<string, import("./lexical-sections.mjs").LexicalSection[]>, declared?: Map<string, Array<{slug:string,heading:string,markdown:string}>>}} generated - From
  *   {@link generatedSectionsFor}.
  * @returns {void}
  */
 export function attachGeneratedSections(prepared, generated) {
+    for (const [absPath, sections] of generated.declared ?? []) {
+        let results = prepared.get(absPath);
+        if (!results) prepared.set(absPath, (results = []));
+        results.declared = sections;
+    }
     for (const [absPath, text] of generated.sections) {
         let results = prepared.get(absPath);
         if (!results) prepared.set(absPath, (results = []));
@@ -1881,11 +1967,18 @@ export async function prepareTreeSqlTables(
         }
     }
     const derivedOnly = await generatedSectionsFor(undefined, indexRecords, contentBase, {
+        parsed,
         foreignIndex: foreign,
         config,
         all: allRecords,
     });
-    if (!sources.length && !hasEvents && !derivedOnly.sections.size && !derivedOnly.lexical.size)
+    if (
+        !sources.length &&
+        !hasEvents &&
+        !derivedOnly.sections.size &&
+        !derivedOnly.lexical.size &&
+        !derivedOnly.declared.size
+    )
         return undefined;
 
     // A page list is a filter over the records, so it needs no database. A tree
@@ -1940,6 +2033,7 @@ export async function prepareTreeSqlTables(
         }));
     try {
         const generated = await generatedSectionsFor(db, indexRecords, contentBase, {
+            parsed,
             derived: derivedOnly.derived,
             all: allRecords,
         });

package/engine/standing-terms.mjs

@@ -35,8 +35,9 @@ export const STANDING_BODY_TYPES = Object.freeze(["affiliation"]);
  * The keys one standing carries, as inner-key declarations.
  *
  * `rank` is the level on the body's own `governance.ranks` ladder, and every
- * membership states one. `office` is a key of its `governance.offices` map, and
- * is stated only where the being holds a post. `societies` names the societies
+ * membership states one. `office` is a key of its `governance.offices` map, or
+ * a list of them where the being holds several posts in that body, and is
+ * stated only where the being holds a post. `societies` names the societies
  * the membership is held in, as a list because a membership can span several.
  *
  * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
@@ -53,9 +54,12 @@ export const STANDING_FIELDS = Object.freeze([
     }),
     Object.freeze({
         name: "office",
-        kind: "string",
-        shape: "a post from that body's `governance.offices`",
-        describe: "A post the body names in its `governance.offices`, where one is held.",
+        kind: "string-or-list",
+        shape: "a post from that body's `governance.offices`, or a list of them",
+        entries: Object.freeze({ kind: "string", shape: "a post" }),
+        describe:
+            "A post the body names in its `governance.offices`, where one is held, or a list of " +
+            "the posts one being holds in that body.",
     }),
     Object.freeze({
         name: "societies",