@jwilleke/ngdpbase-types 5.26.0 → 5.27.0

package/lib/src/export/pdfEngine.js

@@ -0,0 +1,195 @@
+/**
+ * The HTML → PDF engine (#1974): the options and the error every provider
+ * shares, and the child process the `local-chrome` provider renders in
+ * (headless Chromium, driven by `playwright-core`, both optional at run time).
+ *
+ * - `resolveChromium` finds a Chromium to run: the configured path, then the
+ *   one Playwright installed (`npx playwright install chromium`), then the
+ *   usual system locations. Nothing is downloaded at `npm install`.
+ * - `renderPdfInChild` renders one document in a child process
+ *   (`pdfRenderWorker.ts`), killed at the timeout, so the site never waits on
+ *   Chromium or on PDF parsing.
+ * - `normalizePdfInChild` gives a PDF a PDF service made (the
+ *   `chrome-service` provider) the same metadata pass, in the same kind of
+ *   child, so parsing it never runs on the thread that answers requests.
+ *
+ * `ExportManager.htmlToPdf` is the door, through its providers
+ * (`PdfProvider.ts`); nothing else calls these.
+ */
+import { fork } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+/** Page sizes Chromium knows by name. */
+export const PDF_PAGE_SIZES = ['Letter', 'Legal', 'Tabloid', 'Ledger', 'A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6'];
+/** A CSS length Chromium's PDF margins accept: a number and px, in, cm or mm. */
+const MARGIN = /^\d+(\.\d+)?(px|in|cm|mm)$/;
+/**
+ * No PDF engine: `playwright-core` is not installed, no Chromium was found, or
+ * it could not start. An add-on catches it by `code` (it cannot import core
+ * values) and falls back to HTML.
+ */
+export class PdfUnavailableError extends Error {
+    code = 'PDF_UNAVAILABLE';
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'PdfUnavailableError';
+    }
+}
+/**
+ * Validate a caller's options and fill the defaults. Throws on anything
+ * Chromium would misread, so a typo is an error rather than a different page.
+ *
+ * @param options - The caller's options
+ * @param defaultFormat - `ngdpbase.export.pdf.page-size`
+ */
+export function resolvePdfOptions(options, defaultFormat) {
+    const opts = options ?? {};
+    if (typeof opts !== 'object')
+        throw new TypeError('htmlToPdf: options must be an object');
+    const format = opts.format ?? defaultFormat;
+    if (!PDF_PAGE_SIZES.includes(format)) {
+        throw new TypeError(`htmlToPdf: format must be one of ${PDF_PAGE_SIZES.join(', ')} (got ${JSON.stringify(format)})`);
+    }
+    const margin = {};
+    for (const side of ['top', 'right', 'bottom', 'left']) {
+        const value = opts.margin?.[side];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'string' || !MARGIN.test(value)) {
+            throw new TypeError(`htmlToPdf: margin.${side} must be a length such as '20mm' or '0.5in' (got ${JSON.stringify(value)})`);
+        }
+        margin[side] = value;
+    }
+    const printBackground = opts.printBackground ?? true;
+    if (typeof printBackground !== 'boolean')
+        throw new TypeError('htmlToPdf: printBackground must be a boolean');
+    return { format: format, margin, printBackground };
+}
+/** Where Chromium or Chrome usually is, per platform. Checked after the configured path and Playwright's own. */
+export const SYSTEM_CHROMIUM_PATHS = {
+    linux: ['/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/lib/chromium/chromium', '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/snap/bin/chromium'],
+    darwin: ['/Applications/Chromium.app/Contents/MacOS/Chromium', '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'],
+    win32: ['C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe']
+};
+const requireHere = createRequire(import.meta.url);
+/** Whether `playwright-core` is installed (it is an optional dependency). */
+export function playwrightInstalled() {
+    try {
+        requireHere.resolve('playwright-core');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function playwrightChromiumPath() {
+    try {
+        const { chromium } = await import('playwright-core');
+        return chromium.executablePath() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find a Chromium to render with. Read on every call, so installing Chromium
+ * or setting the path takes effect without a restart.
+ *
+ * @param configuredPath - `ngdpbase.export.pdf.provider.local-chrome.chromium-path` ('' = find one)
+ */
+export async function resolveChromium(configuredPath, deps = {}) {
+    const exists = deps.exists ?? existsSync;
+    if (!(deps.playwrightInstalled ?? playwrightInstalled)()) {
+        return { ok: false, reason: 'playwright-core is not installed (it is an optional dependency; npm install without --omit=optional)' };
+    }
+    if (configuredPath) {
+        return exists(configuredPath)
+            ? { ok: true, executablePath: configuredPath, source: 'configured' }
+            : { ok: false, reason: `ngdpbase.export.pdf.provider.local-chrome.chromium-path is set, but nothing is there: ${configuredPath}` };
+    }
+    const bundled = await (deps.playwrightChromium ?? playwrightChromiumPath)();
+    if (bundled && exists(bundled))
+        return { ok: true, executablePath: bundled, source: 'playwright' };
+    for (const candidate of SYSTEM_CHROMIUM_PATHS[deps.platform ?? process.platform] ?? []) {
+        if (exists(candidate))
+            return { ok: true, executablePath: candidate, source: 'system' };
+    }
+    return { ok: false, reason: 'no Chromium found: install Chromium, or set ngdpbase.export.pdf.provider.local-chrome.chromium-path' };
+}
+/**
+ * The environment the child gets: enough to find a home, a temp folder and
+ * fonts, and none of the site's secrets (the session secret, keys and
+ * passwords the site holds in its environment).
+ */
+const CHILD_ENV_KEYS = [
+    'PATH', 'HOME', 'TMPDIR', 'TMP', 'TEMP', 'LANG', 'LC_ALL', 'PLAYWRIGHT_BROWSERS_PATH',
+    'FONTCONFIG_PATH', 'FONTCONFIG_FILE', 'XDG_CONFIG_HOME', 'XDG_CACHE_HOME', 'XDG_RUNTIME_DIR',
+    'SystemRoot', 'LOCALAPPDATA', 'USERPROFILE', 'APPDATA', 'ProgramFiles', 'ProgramFiles(x86)'
+];
+export function childEnv(env = process.env) {
+    const out = {};
+    for (const key of CHILD_ENV_KEYS)
+        if (env[key] !== undefined)
+            out[key] = env[key];
+    return out;
+}
+/**
+ * Render one job in a child process. Resolves with the child's answer; rejects
+ * only when the child timed out, crashed or never answered.
+ *
+ * @param job - The render
+ */
+export function renderPdfInChild(job) {
+    return runPdfChild(job);
+}
+/**
+ * Normalise a PDF in a child process (`normalizePdf`, the same pass a local
+ * render gets). Rejects when the bytes are not a PDF pdf-lib can read, or the
+ * child times out.
+ *
+ * @param pdf - A PDF a PDF service returned
+ * @param timeoutMs - The child is killed after this
+ */
+export async function normalizePdfInChild(pdf, timeoutMs) {
+    const result = await runPdfChild({ kind: 'normalize', pdf, timeoutMs });
+    if (!result.ok)
+        throw new Error(`the PDF could not be read: ${result.error}`);
+    return result.pdf;
+}
+function runPdfChild(job) {
+    // Compiled, the worker is the .js beside this file. From source (vitest,
+    // tsx) it is the .ts, which needs tsx's loader.
+    const fromSource = import.meta.url.endsWith('.ts');
+    const entry = new URL(fromSource ? './pdfRenderWorker.ts' : './pdfRenderWorker.js', import.meta.url);
+    return new Promise((resolve, reject) => {
+        const child = fork(entry, [], {
+            execArgv: fromSource ? ['--import', 'tsx'] : [],
+            env: childEnv(),
+            serialization: 'advanced',
+            stdio: ['ignore', 'ignore', 'pipe', 'ipc']
+        });
+        let settled = false;
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => { if (stderr.length < 2000)
+            stderr += chunk.toString(); });
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            settle(() => reject(new Error(`PDF render timed out after ${job.timeoutMs} ms`)));
+            child.kill('SIGKILL');
+        }, job.timeoutMs);
+        child.once('message', (result) => {
+            settle(() => resolve(result.ok ? { ok: true, pdf: Buffer.from(result.pdf) } : result));
+        });
+        child.once('error', (err) => settle(() => reject(err)));
+        child.once('exit', (code, signal) => {
+            settle(() => reject(new Error(`PDF render process exited (${signal ?? code}) without an answer${stderr ? `: ${stderr.trim().split('\n')[0]}` : ''}`)));
+        });
+        child.send(job);
+    });
+}

package/lib/src/ice/converterShim.d.ts

@@ -0,0 +1,5 @@
+import type { IContentConverter } from '../converters/IContentConverter.js';
+import type { IceShim } from './types.js';
+/** The receiver today's converters hand to. */
+export declare const PAGES_RECEIVER = "core.pages";
+export declare function converterShim(converter: IContentConverter, tableClasses: () => string[]): IceShim;

package/lib/src/ice/fileHandling.d.ts

@@ -0,0 +1,30 @@
+import { type ZipReadLimits } from '../utils/zipArchive.js';
+import type { IceUpload } from './types.js';
+/** A file's fingerprint: SHA-256 of its bytes, hex. */
+export declare function fingerprint(bytes: Buffer): string;
+/**
+ * Is this path noise — something an operating system or archiver adds that is
+ * nobody's data? Patterns (configuration, `ngdpbase.import.engine.noise`):
+ *
+ * - `name/` — any path with a directory segment of that name (`__MACOSX/`);
+ * - `prefix*` / `*suffix` — a file name starting or ending so (`._*`);
+ * - anything else — a file name exactly (`.DS_Store`), case-insensitive.
+ */
+export declare function isNoise(filePath: string, patterns: readonly string[]): boolean;
+/** Is this upload a zip archive the engine unpacks? By its name, or its media type. */
+export declare function isZip(upload: IceUpload): boolean;
+/**
+ * Unpack the zips among the uploads into the files they hold, named
+ * `archive.zip/inner/path`. A nested zip is unpacked too. Everything else is
+ * passed through. Limits are per archive (`ZipReadLimits`), so a small
+ * archive that expands enormously stops at the budget. An archive that cannot
+ * be read is returned in `unreadable`, with why; the rest go on.
+ */
+export declare function expandUploads(uploads: readonly IceUpload[], limits: ZipReadLimits, maxDepth: number, depth?: number): {
+    files: IceUpload[];
+    unreadable: Array<{
+        name: string;
+        size: number;
+        message: string;
+    }>;
+};

package/lib/src/ice/ledger.d.ts

@@ -0,0 +1,37 @@
+import type { IceLedger, LedgerFileEntry } from './types.js';
+interface ScopeFile {
+    scope: string;
+    files: LedgerFileEntry[];
+    items: string[];
+}
+/** Keeps the newest entry per fingerprint, at most `maxEntries` files and item keys per scope. */
+declare abstract class ScopedLedger implements IceLedger {
+    private readonly maxEntries;
+    constructor(maxEntries: number);
+    protected abstract load(scope: string): Promise<ScopeFile>;
+    protected abstract save(data: ScopeFile): Promise<void>;
+    /** One writer per scope at a time, so two runs in one scope cannot lose each other's entries. */
+    private readonly chains;
+    private serial;
+    lastFile(scope: string, sha256: string): Promise<LedgerFileEntry | null>;
+    recordFile(scope: string, entry: LedgerFileEntry): Promise<void>;
+    hasItem(scope: string, itemKey: string): Promise<boolean>;
+    recordItem(scope: string, itemKey: string): Promise<void>;
+    files(scope: string): Promise<LedgerFileEntry[]>;
+}
+/** The ledger in memory: for tests, and for a site that keeps no import history. */
+export declare class MemoryIceLedger extends ScopedLedger {
+    private readonly scopes;
+    constructor(maxEntries?: number);
+    protected load(scope: string): Promise<ScopeFile>;
+    protected save(data: ScopeFile): Promise<void>;
+}
+/** One JSON file per scope, named by the scope's hash (a scope holds a username). */
+export declare class FileIceLedger extends ScopedLedger {
+    private readonly dir;
+    constructor(dir: string, maxEntries: number);
+    private fileFor;
+    protected load(scope: string): Promise<ScopeFile>;
+    protected save(data: ScopeFile): Promise<void>;
+}
+export {};

package/lib/src/ice/runImport.d.ts

@@ -0,0 +1,51 @@
+import type { ActorContext } from '../context/ActorContext.js';
+import type { ZipReadLimits } from '../utils/zipArchive.js';
+import type { IceItem, IceLedger, IceRunReport, IceRunRequest, OriginalChoice, RegisteredReceiver, RegisteredShim, ShimTools } from './types.js';
+/** Configuration the engine reads (each a key under `ngdpbase.import.engine.`). */
+export interface IceEngineSettings {
+    noise: string[];
+    zip: ZipReadLimits;
+    maxZipDepth: number;
+    maxFileBytes: number;
+    maxChainDepth: number;
+    defaultOriginal: OriginalChoice;
+}
+export interface IceRunDeps {
+    /** Enabled shims, in registration order. */
+    shims: RegisteredShim[];
+    receivers: ReadonlyMap<string, RegisteredReceiver>;
+    ledger: IceLedger;
+    settings: IceEngineSettings;
+    tools(shim: RegisteredShim): ShimTools;
+    now?: () => Date;
+}
+/** The id of the receiver that keeps an original when the chosen receiver does not keep its own (D11). */
+export declare const FILES_RECEIVER = "core.files";
+/** The scope a run's fingerprints are checked in, unless the caller names one. */
+export declare function defaultScope(receiverId: string, ctx: ActorContext): string;
+export interface ChainLeaf {
+    item: IceItem;
+    chain: string[];
+}
+/** What a chain needs: the shims it may continue through, and where it stops. */
+export interface ChainSpec {
+    shims: RegisteredShim[];
+    tools(shim: RegisteredShim): ShimTools;
+    maxChainDepth: number;
+    /** Does this item, from this shim, stop here? */
+    done(shim: RegisteredShim, item: IceItem): boolean;
+    /** Named in the error when nothing takes an item further. */
+    target: string;
+}
+/**
+ * Run a shim, then the shims after it (D9), until each item is done. What
+ * came before travels with each item: earlier metadata under later, earlier
+ * warnings first. Partial notes are collected into `partial`.
+ */
+export declare function convertChain(shim: RegisteredShim, input: IceItem, chain: string[], spec: ChainSpec, partial: string[]): Promise<ChainLeaf[]>;
+/**
+ * Run one import. Fills and returns `report`, which the caller may be
+ * showing while it runs. Never throws for one file's failure; that file's
+ * status says why.
+ */
+export declare function runImport(deps: IceRunDeps, request: IceRunRequest, ctx: ActorContext, report: IceRunReport): Promise<IceRunReport>;

package/lib/src/ice/types.d.ts

@@ -0,0 +1,262 @@
+/**
+ * ICE — import, convert, export (#1979): the shapes the engine, its shims and
+ * its receivers share. The design and every decision (D1–D11) are in
+ * docs/planning/ice-planing.md; this file is their code form.
+ *
+ * - A __shim__ knows one outside format and nothing else (D2). It declares
+ *   its direction, what it accepts, what it produces and which receivers it
+ *   may hand to (D3, D7). Shims chain: one's output is the next one's input (D9).
+ * - A __receiver__ is a door that already exists — PageManager for pages, the
+ *   upload door for files, an add-on's own manager for its records (D4). The
+ *   engine hands it each result and never writes storage itself. The receiver
+ *   checks its own existing permission with the context the run carries (D5).
+ * - The __engine__ (ImportManager) owns everything else: sources, unzip, the
+ *   noise filter, fingerprints, skipping unchanged files, per-file status,
+ *   keeping the original, and running the work as a background job.
+ *
+ * Only importing is built in the first slice. `out` / `both` shims and the
+ * `write` half are declared so export (#1974) and feeds (D10) fit later
+ * without changing these shapes.
+ */
+import type { ActorContext } from '../context/ActorContext.js';
+import type { GuardedFetchOptions, GuardedResponse } from '../http/guardedFetch.js';
+/** D3: which way a shim moves data. Most are `in`; PDF (#1974) would be `both`. */
+export type ShimDirection = 'in' | 'out' | 'both';
+/**
+ * The kind of a piece of content moving through the engine. `file` is raw
+ * input bytes; `html` and `ncm` are core's; an add-on's own kinds are named
+ * `<slug>.<kind>`, e.g. `phr.health-record`.
+ */
+export type IceKind = string;
+/** A structured note from a shim, the same shape as a converter's warning. */
+export interface IceWarning {
+    kind: string;
+    detail: string;
+}
+/**
+ * One piece of content: a file the engine read, or what a shim produced from
+ * it. A shim's output becomes the next shim's input, or a receiver's.
+ */
+export interface IceItem {
+    kind: IceKind;
+    /** The name it arrived under: the upload's file name, or `archive.zip/inner/path`. */
+    name: string;
+    mediaType?: string;
+    /** Raw bytes (a `file`, or binary output). */
+    bytes?: Buffer;
+    /** Text content (`html`, `ncm`, an XML document). */
+    text?: string;
+    /** A structured record, for record kinds such as health records. */
+    data?: unknown;
+    /** Facts about the content: a title, an author, a source system's id. */
+    metadata?: Record<string, unknown>;
+    warnings?: IceWarning[];
+    /**
+     * The item's own id or time, for a shim whose duplicates are per item
+     * (a feed entry): an item whose key the engine has seen before is skipped.
+     */
+    itemKey?: string;
+}
+/** What a shim takes. A file matches by extension or media type; a chained input by kind. */
+export interface ShimAccepts {
+    /** Lower-case, with the dot: `['.xml']`. */
+    extensions?: string[];
+    mediaTypes?: string[];
+    /** Kinds produced by another shim that this one reads (D9), e.g. `['html']`. */
+    kinds?: IceKind[];
+    /**
+     * "Can I read this?" (D7), on the content. When present it must answer yes
+     * even for a file whose extension matches; it is also how a file with no
+     * matching extension is claimed.
+     */
+    canRead?(input: IceItem): boolean;
+}
+/** What the engine hands a shim besides its input. */
+export interface ShimTools {
+    /**
+     * Follow-up fetches go through the engine (design rule): the one guarded
+     * path, with the site's egress policy, User-Agent and timeout.
+     */
+    fetch(url: string, options?: Omit<GuardedFetchOptions, 'policy' | 'transport' | 'resolver'>): Promise<GuardedResponse>;
+    /** This shim's options from site configuration (D6): `ngdpbase.import.shims.<id>.options`. */
+    options: Record<string, unknown>;
+}
+/** What a shim's read returns. */
+export interface ShimReadResult {
+    items: IceItem[];
+    /**
+     * Set when the shim read only part of its input (phr's `readCcda` returns
+     * records plus a partial note): the file's status is then `partial`, with this.
+     */
+    partial?: string;
+}
+/**
+ * A shim as its author writes it (D7). `name` is unique within its owner; the
+ * engine names it `<owner>.<name>` — `core.markdown`, `phr.ccda`.
+ */
+export interface IceShim {
+    name: string;
+    /** Shown to people choosing a format. */
+    label?: string;
+    direction: ShimDirection;
+    accepts: ShimAccepts;
+    /** The kind its output items have. */
+    produces: IceKind;
+    /**
+     * Receivers it may hand to directly (ids, `core.pages` or `<slug>.<name>`).
+     * Empty for a shim whose output only feeds another shim.
+     */
+    receivers: string[];
+    /** Two duplicate kinds (design rule): a whole file by fingerprint, or each item by `itemKey`. Default `file`. */
+    duplicates?: 'file' | 'item';
+    /** Inbound: read one input. Required for `in` and `both`. */
+    read?(input: IceItem, tools: ShimTools): Promise<ShimReadResult>;
+    /** Outbound (export, #1974): not run in the first slice. Required for `out` and `both`. */
+    write?(items: IceItem[], tools: ShimTools): Promise<IceItem[]>;
+}
+/** A shim the engine holds: its full id, and who registered it. */
+export interface RegisteredShim extends IceShim {
+    id: string;
+    owner: string;
+}
+/** D11: what the person importing chose to do with the original file. */
+export type OriginalChoice = 'cite' | 'keep' | 'none';
+/** A citation to the origin (D11): the receiver renders it, as a footnote on a page. */
+export interface IceCitation {
+    name: string;
+    sha256: string;
+    importedAt: string;
+}
+/** Where a kept original went (D11). */
+export interface KeptOriginal {
+    name: string;
+    sha256: string;
+    /** The keeping door's own reference: an attachment id, a record id. */
+    ref: string;
+}
+/** What a receiver is told about the item it is handed. */
+export interface ReceiveInfo {
+    runId: string;
+    /** The file the item came from. */
+    source: {
+        name: string;
+        sha256: string;
+    };
+    /** The shims the item passed through, in order. */
+    chain: string[];
+    citation?: IceCitation;
+    original?: KeptOriginal;
+}
+/** A receiver's answer for one item. `refused` is its existing permission saying no (D5). */
+export interface ReceiveOutcome {
+    status: 'stored' | 'duplicate' | 'refused';
+    /** Where it went: a page name, an attachment id, a record id. */
+    ref?: string;
+    message?: string;
+}
+/**
+ * A receiver as its owner writes it (D4). Its doors are the receiver's own
+ * existing ones; each checks its own permission with the context given (D5).
+ */
+export interface IceReceiver {
+    name: string;
+    label?: string;
+    /** The kinds it takes, e.g. `['ncm']`, `['file']`, `['phr.health-record']`. */
+    accepts: IceKind[];
+    /** May this context use this receiver? Its existing permission — the import screen shows only these (D5). */
+    mayUse(ctx: ActorContext): Promise<boolean>;
+    /** Hand one item to the receiver's own door. */
+    receive(item: IceItem, ctx: ActorContext, info: ReceiveInfo): Promise<ReceiveOutcome>;
+    /**
+     * Keep the original file itself (D11: phr keeps originals in its own
+     * store). Without this, `keep` hands the original to the files receiver.
+     */
+    keepOriginal?(original: IceItem, ctx: ActorContext): Promise<ReceiveOutcome>;
+}
+export interface RegisteredReceiver extends IceReceiver {
+    id: string;
+    owner: string;
+}
+/** One file handed to the engine. A `.zip` is unpacked by the engine. */
+export interface IceUpload {
+    name: string;
+    bytes: Buffer;
+    mediaType?: string;
+}
+/**
+ * A source (D1). The first slice reads uploads; a URL fetched on a schedule
+ * (D10, feeds) and a server folder join this union later.
+ */
+export type IceSource = {
+    type: 'upload';
+    files: IceUpload[];
+};
+/** One import, as a caller asks for it. */
+export interface IceRunRequest {
+    source: IceSource;
+    /** The receiver id the results go to: `core.pages`, `phr.health-records`. */
+    receiver: string;
+    /** Pin the first shim (a format the person chose) instead of detecting one. */
+    shim?: string;
+    /** D11. Default `ngdpbase.import.engine.default-original`. */
+    original?: OriginalChoice;
+    /**
+     * Whose fingerprints and item keys this run is checked against. Default
+     * `<receiver>/<username>`: the same file imported again by the same person
+     * into the same receiver is skipped. A caller with its own notion of a
+     * source (phr's source id) passes it.
+     */
+    scope?: string;
+}
+/** Per-file status (first slice). */
+export type IceFileStatus = 'imported' | 'partial' | 'unchanged' | 'duplicate' | 'noise' | 'unreadable' | 'refused' | 'failed';
+export interface IceFileReport {
+    name: string;
+    sha256?: string;
+    size: number;
+    status: IceFileStatus;
+    message?: string;
+    /** The shims the file went through. */
+    chain: string[];
+    /** Where each item went. */
+    refs: string[];
+    /** Items stored, and items skipped as already seen. */
+    stored: number;
+    duplicates: number;
+    original?: KeptOriginal;
+    warnings: IceWarning[];
+}
+export interface IceRunReport {
+    runId: string;
+    receiver: string;
+    scope: string;
+    /** Who it ran as. */
+    username: string;
+    state: 'queued' | 'running' | 'done' | 'failed';
+    startedAt?: string;
+    finishedAt?: string;
+    error?: string;
+    files: IceFileReport[];
+}
+/** What the engine remembers about one file in a scope. */
+export interface LedgerFileEntry {
+    name: string;
+    sha256: string;
+    size: number;
+    status: IceFileStatus;
+    message?: string;
+    at: string;
+    refs: string[];
+}
+/**
+ * Where the engine keeps fingerprints, per-file status and item keys, per
+ * scope. One interface so a database table can replace the file store when
+ * the application database is on.
+ */
+export interface IceLedger {
+    lastFile(scope: string, sha256: string): Promise<LedgerFileEntry | null>;
+    recordFile(scope: string, entry: LedgerFileEntry): Promise<void>;
+    hasItem(scope: string, itemKey: string): Promise<boolean>;
+    recordItem(scope: string, itemKey: string): Promise<void>;
+    files(scope: string): Promise<LedgerFileEntry[]>;
+}

package/lib/src/mail/MailProvider.d.ts

@@ -20,7 +20,22 @@ export interface MailMessage {
     text: string;
     /** Optional HTML body */
     html?: string;
+    /** Files sent with the message (#1974); their total is capped by `ngdpbase.mail.attachments.max-bytes`. */
+    attachments?: MailAttachment[];
 }
+/**
+ * One file attached to a message (#1974), as Nodemailer takes it. The content
+ * is never logged: a log line says how many files and how many bytes.
+ */
+export interface MailAttachment {
+    /** The name the recipient sees, e.g. `invoice-2026-0042.pdf`. */
+    filename: string;
+    /** Its media type, e.g. `application/pdf`. */
+    contentType: string;
+    content: Buffer;
+}
+/** How many files and bytes a message carries — the only thing a log line says about attachments. */
+export declare function describeAttachments(attachments: MailAttachment[] | undefined): string;
 /**
  * Common interface for all mail transports.
  */

package/lib/src/mail/NodemailerMailProvider.d.ts

@@ -9,7 +9,7 @@
  *   ngdpbase.mail.provider.smtp.pass
  *   ngdpbase.mail.provider.smtp.from
  */
-import type { MailMessage, MailProvider } from './MailProvider.js';
+import { type MailMessage, type MailProvider } from './MailProvider.js';
 export interface SmtpConfig {
     host: string;
     port: number;

package/lib/src/managers/AddonsManager.d.ts

@@ -238,6 +238,19 @@ export interface AddonManifest {
     family?: string;
     /** #1965: `false` keeps plumbing (e.g. elasticsearch) out of the add-on listings. */
     listed?: boolean;
+    /**
+     * #1979 (ICE, D6): the names of the import shims this add-on registers at
+     * load with `host.registerShim`, e.g. `["ccda", "fhir"]` (ids `<slug>.ccda`,
+     * `<slug>.fhir`). The host refuses a shim not named here. Site configuration
+     * switches each one: `ngdpbase.import.shims.<slug>.<name>.enabled`.
+     */
+    shims?: string[];
+    /**
+     * #1979 (ICE, D4): the names of the receivers this add-on registers with
+     * `host.registerReceiver` — its own manager's door for what shims produce,
+     * e.g. `["health-records"]`. The host refuses a receiver not named here.
+     */
+    receivers?: string[];
 }
 /**
  * One add-on as the listings show it (#1965), from `AddonsManager.listedAddons()`.
@@ -715,8 +728,11 @@ declare class AddonsManager extends BaseManager {
      * documents: they guard the per-person switch, so only such an add-on has any.
      */
     isPerPerson(slug: string): boolean;
-    /** #1963: the loaded add-ons whose manifest says `perPerson: true`, in load order. */
-    private perPersonAddons;
+    /**
+     * #1963: the loaded add-ons whose manifest says `perPerson: true`, in load
+     * order — every slug an `addon:<slug>` page audience can match (#1964).
+     */
+    perPersonAddons(): string[];
     /**
      * The per-person add-ons this subject has turned on (#1963): each loaded
      * add-on whose manifest says `perPerson: true` and whose switch, the