@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/providers/SqliteJobStateProvider.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Scheduled-job state in the application database (#1714). See `jobState.ts`.
+ *
+ * Uses the one connection `DatabaseManager.getHandle()` hands out — never a
+ * database file of its own — so it is encrypted when the database is
+ * (SQLCipher, `NGDPBASE_DATABASE_KEY`). The tables come from the core
+ * migration ledger (`databaseMigrations.ts`, 20261008180000).
+ *
+ * A lock is a row in `job_leases`, taken by one conditional write: insert it,
+ * or overwrite it only when it has expired or already belongs to the caller.
+ * SQLite runs that statement as one unit, so of any servers racing for a slot
+ * exactly one sees its row change.
+ *
+ * @module providers/SqliteJobStateProvider
+ */
+import type Database from 'better-sqlite3-multiple-ciphers';
+import { type JobRunRecord, type JobState, type JobStateLimits, type JobStateProvider } from './jobState.js';
+type Handle = InstanceType<typeof Database>;
+export interface SqliteJobStateOptions extends JobStateLimits {
+    /** For tests: the clock. */
+    now?: () => number;
+}
+declare class SqliteJobStateProvider implements JobStateProvider {
+    private readonly db;
+    readonly backend: "sqlite";
+    private readonly historyLimit;
+    private readonly checkpointMaxBytes;
+    private readonly now;
+    constructor(db: Handle, options?: SqliteJobStateOptions);
+    getState(jobId: string): Promise<JobState | null>;
+    putState(state: JobState): Promise<void>;
+    recordRun(jobId: string, run: JobRunRecord): Promise<void>;
+    listRuns(jobId: string): Promise<JobRunRecord[]>;
+    saveCheckpoint(jobId: string, runId: string, data: unknown): Promise<void>;
+    loadCheckpoint(jobId: string, runId: string): Promise<unknown>;
+    clearCheckpoint(jobId: string, runId: string): Promise<void>;
+    takeLock(jobId: string, slot: string, owner: string, ttlMs: number): Promise<boolean>;
+    renewLock(jobId: string, slot: string, owner: string, ttlMs: number): Promise<boolean>;
+    releaseLock(jobId: string, slot: string, owner: string): Promise<void>;
+}
+export default SqliteJobStateProvider;

package/lib/src/providers/databaseMigrations.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The application database's migration ledger (#1536), strictly ascending by
+ * id (YYYYMMDDHHMMSS). Each entry is a frozen snapshot of what it did on its
+ * date; see `sqliteMigrations.ts`.
+ */
+import type { Migration } from './sqliteMigrations.js';
+declare const DATABASE_MIGRATIONS: Migration[];
+export default DATABASE_MIGRATIONS;

package/lib/src/providers/databaseMigrations.js

@@ -0,0 +1,47 @@
+const DATABASE_MIGRATIONS = [
+    {
+        // #1714: scheduled-job state, history, checkpoints and slot locks.
+        id: '20261008180000',
+        description: 'scheduled jobs: job_state, job_runs, job_checkpoints, job_leases',
+        up: (db) => {
+            db.exec(`CREATE TABLE job_state (
+        job_id TEXT PRIMARY KEY,
+        last_slot_done TEXT,
+        next_slot TEXT,
+        current_run TEXT,
+        updated_at TEXT NOT NULL
+      )`);
+            db.exec(`CREATE TABLE job_runs (
+        run_id TEXT PRIMARY KEY,
+        job_id TEXT NOT NULL,
+        started_at TEXT NOT NULL,
+        record TEXT NOT NULL
+      )`);
+            db.exec('CREATE INDEX job_runs_by_job ON job_runs (job_id, started_at)');
+            db.exec(`CREATE TABLE job_checkpoints (
+        job_id TEXT NOT NULL,
+        run_id TEXT NOT NULL,
+        data TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (job_id, run_id)
+      )`);
+            db.exec(`CREATE TABLE job_leases (
+        job_id TEXT NOT NULL,
+        slot TEXT NOT NULL,
+        owner TEXT NOT NULL,
+        expires_at INTEGER NOT NULL,
+        PRIMARY KEY (job_id, slot)
+      )`);
+        }
+    },
+    {
+        // #1715: the schedule a job's slots were computed from, so a rule changed
+        // while the server was down is recomputed rather than caught up.
+        id: '20261009140000',
+        description: 'scheduled jobs: job_state.rule',
+        up: (db) => {
+            db.exec('ALTER TABLE job_state ADD COLUMN rule TEXT');
+        }
+    }
+];
+export default DATABASE_MIGRATIONS;

package/lib/src/providers/jobState.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Where scheduled jobs keep what must survive a restart (#1714, epic #1611):
+ * each job's last slot done, its next slot and its current run, a capped run
+ * history, a run's checkpoint, and the lock that lets exactly one server run a
+ * slot.
+ *
+ * Two backends, one contract (`__tests__/jobStateContract.ts` runs against
+ * both):
+ *   - `file` — JSON in FAST_STORAGE, written atomically; a lock is a file
+ *     created exclusively;
+ *   - `sqlite` — tables in the application database (DatabaseManager), changed
+ *     in transactions; a lock is a row taken by a conditional write.
+ *
+ * `selectJobStateBackend` reads `ngdpbase.jobs.state.provider`: `auto` picks
+ * `sqlite` when the application database is open, else `file`. Switching
+ * backends carries nothing across: the new one starts empty, next slots are
+ * recomputed and missed slots are not caught up.
+ *
+ * @module providers/jobState
+ */
+import type { JobContext } from '../context/JobContext.js';
+/** One run of a job. Times are ISO 8601 instants. */
+export interface JobRunRecord {
+    runId: string;
+    /** The slot this run is for; null for a run someone started by hand. */
+    slot: string | null;
+    startedAt: string;
+    /** 1 for the first try; a run resumed after a restart counts up. */
+    attempt: number;
+    /** `skipped`: a slot the scheduler passed over, by its catch-up or overlap rule (#1715). */
+    status: 'running' | 'completed' | 'failed' | 'interrupted' | 'skipped';
+    completedAt?: string;
+    error?: string;
+    /** A failed attempt with attempts left: when it is tried again (#1716). */
+    retryAt?: string;
+    /**
+     * Who asked, for a run started by hand (#1746): the run is restarted as
+     * them after a restart, or reported to them. `null` for a scheduled slot,
+     * which runs as the system principal — said on purpose (#1399), never left
+     * out. A record written before this field existed reads as having none.
+     */
+    requestedBy: JobContext | null;
+}
+export interface JobState {
+    jobId: string;
+    lastSlotDone: string | null;
+    /** The first slot not yet handled: run, skipped or failed (#1715). */
+    nextSlot: string | null;
+    current: JobRunRecord | null;
+    /**
+     * The schedule the slots were computed from (`rrule|dtstart|timeZone`), so a
+     * rule changed while the server was down is seen at the next start: slots
+     * are recomputed from then, and nothing is caught up for the old rule
+     * (#1715). Null for state written before the rule was kept.
+     */
+    rule: string | null;
+}
+export interface JobStateLimits {
+    /** Runs kept per job (`ngdpbase.jobs.history-limit`). Default 50. */
+    historyLimit?: number;
+    /** Largest checkpoint accepted, in bytes of JSON. Default 256 KiB. */
+    checkpointMaxBytes?: number;
+}
+export declare const DEFAULT_HISTORY_LIMIT = 50;
+export declare const DEFAULT_CHECKPOINT_MAX_BYTES: number;
+export interface JobStateProvider {
+    readonly backend: 'file' | 'sqlite';
+    getState(jobId: string): Promise<JobState | null>;
+    putState(state: JobState): Promise<void>;
+    /** Add or replace a run in the job's history, keeping the newest `historyLimit`. */
+    recordRun(jobId: string, run: JobRunRecord): Promise<void>;
+    /** The job's runs, newest first. */
+    listRuns(jobId: string): Promise<JobRunRecord[]>;
+    /** Throws when the JSON is larger than `checkpointMaxBytes`. */
+    saveCheckpoint(jobId: string, runId: string, data: unknown): Promise<void>;
+    loadCheckpoint(jobId: string, runId: string): Promise<unknown>;
+    clearCheckpoint(jobId: string, runId: string): Promise<void>;
+    /**
+     * Take the lock for one slot, or steal it when its holder let it expire.
+     * True for exactly one caller among any that contend.
+     */
+    takeLock(jobId: string, slot: string, owner: string, ttlMs: number): Promise<boolean>;
+    /** Extend a lock this owner holds. False when it no longer holds it. */
+    renewLock(jobId: string, slot: string, owner: string, ttlMs: number): Promise<boolean>;
+    /** Give up a lock this owner holds; a lock held by another owner is left alone. */
+    releaseLock(jobId: string, slot: string, owner: string): Promise<void>;
+    close?(): void;
+}
+export declare function assertJobId(jobId: string): void;
+/** A slot as a compact UTC stamp, safe in a file name: `20261008T060000Z`. */
+export declare function slotKey(slot: string): string;
+/** The JSON a checkpoint is stored as, refused when larger than the cap. */
+export declare function checkpointJson(data: unknown, maxBytes: number): string;
+/**
+ * Which backend `ngdpbase.jobs.state.provider` names. `auto` (the default)
+ * picks `sqlite` when the application database is open. `sqlite` with no
+ * database open is an error naming the key to set.
+ */
+export declare function selectJobStateBackend(configured: unknown, databaseEnabled: boolean): 'file' | 'sqlite';

package/lib/src/providers/lunrQueryToMiniSearch.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Lunr-style query strings, read as MiniSearch query trees (#1736).
+ *
+ * The search provider moved from Lunr to MiniSearch, but its callers still
+ * speak Lunr's query language: the field-scoped search builds `+title:word`,
+ * type-ahead appends `*` to the last term (`applyPrefixToLastTerm`), and a
+ * person may type any of it into the search box. This keeps that language,
+ * with the same meaning:
+ *
+ *   word          an optional term; with no required terms, any one matches
+ *   +word         required: every result contains it
+ *   -word         excluded: no result contains it
+ *   field:word    only that field (an unknown field is read as plain text, so
+ *                 a typed URL such as `https://x` is a search, not an error)
+ *   word*         prefix match
+ *   word~1        fuzzy match, up to that edit distance
+ *
+ * A term's `^boost` is accepted and ignored. When required terms are present,
+ * optional terms no longer narrow the results (as in Lunr); they are not used
+ * for ranking either.
+ *
+ * @module providers/lunrQueryToMiniSearch
+ */
+import { type Query } from 'minisearch';
+/**
+ * The MiniSearch query for a Lunr-style string, or null when the string holds
+ * nothing to search for.
+ *
+ * @param query  - the query as a caller or a person wrote it
+ * @param fields - the indexed field names; a `field:` prefix naming another is plain text
+ */
+export declare function lunrQueryToMiniSearch(query: string, fields: readonly string[]): Query | null;

package/lib/src/providers/mediaFilenameDate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Conservative filename → capture-date parser (#809, slice C of #807).
+ *
+ * Last-resort fallback used by media providers when a file carries no usable
+ * EXIF/QuickTime capture date. Many devices encode the capture time in the
+ * filename (e.g. `PXL_20260113_123414708.jpg`, `2026-04-03-IMG_4654.jpg`,
+ * `Feb_20_2026_19_25_04.jpg`); without this, those files index with
+ * `dateTimeOriginal: null` and sort only by file `mtime`.
+ *
+ * Design constraints (from the issue):
+ *   - **Conservative** — only a small set of high-confidence, anchored patterns
+ *     are accepted. Anything ambiguous returns `null`, and the caller then
+ *     falls back to `mtime` and surfaces the file to admins.
+ *   - **Distinguishable provenance** — the caller records that the resulting
+ *     date came from the filename (`captureDateSource: 'filename'`), so a
+ *     parsed date never masquerades as authoritative EXIF metadata.
+ *
+ * Returns a `"YYYY-MM-DD HH:MM:SS"` string (the exact shape produced by the
+ * EXIF extractor, so it flows through sort/filter identically), or `null`.
+ * A date-only match yields a `00:00:00` time.
+ */
+export declare function parseDateFromFilename(filename: string): string | null;

package/lib/src/providers/sqliteLocation.d.ts

@@ -0,0 +1,17 @@
+/** Linux statfs f_type values for network filesystems (linux/magic.h). */
+export declare const NETWORK_FILESYSTEMS: Readonly<Record<number, string>>;
+export interface StatFsLike {
+    type: number;
+}
+/** The network filesystem `target` would live on, or null (#1714: shared by the SQLite and file stores). */
+export declare function networkFilesystemAt(target: string, statfs?: (path: string) => StatFsLike, platform?: string): {
+    name: string;
+    probe: string;
+    type: number;
+} | null;
+/**
+ * Throws, naming the path and the filesystem, when `databaseFile` would be opened on a network
+ * filesystem. A file that does not exist yet is judged by the nearest directory that does, since
+ * that is where SQLite will create it.
+ */
+export declare function refuseNetworkFilesystem(databaseFile: string, statfs?: (path: string) => StatFsLike, platform?: string): void;

package/lib/src/providers/sqliteLocation.js

@@ -0,0 +1,55 @@
+/**
+ * SQLite must not live on a network filesystem (ported from yourPHR, yourphr#628; ngdpbase #1536).
+ *
+ * Every database here runs in WAL mode, and WAL coordinates readers and writers through a `-shm`
+ * file each connection mmaps shared-writable. That does not work over NFS or SMB, and SQLite
+ * documents WAL there as unsupported: the database will not open, or opens and corrupts — on PHI,
+ * discovered at restore time. So the boot stats where each database will ACTUALLY live, whatever root
+ * it was composed from or however it was labelled, and refuses when that is a known network
+ * filesystem.
+ *
+ * Deliberately narrow, as the issue decided:
+ *   - fail-CLOSED on a known-bad type, fail-OPEN on anything unrecognised — the magic numbers are
+ *     Linux's; a laptop's APFS (0x1a on macOS) must boot, not be refused;
+ *   - boot-time only: a path that becomes a mount later is not re-checked;
+ *   - SQLite files only. The backup destination SHOULD be on a NAS, and is never checked here.
+ */
+import { existsSync, statfsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/** Linux statfs f_type values for network filesystems (linux/magic.h). */
+export const NETWORK_FILESYSTEMS = {
+    0x6969: 'NFS',
+    0x517b: 'SMB',
+    0xff534d42: 'CIFS',
+    0xfe534d42: 'SMB2'
+};
+/** The network filesystem `target` would live on, or null (#1714: shared by the SQLite and file stores). */
+export function networkFilesystemAt(target, statfs = (p) => statfsSync(p), platform = process.platform) {
+    if (platform !== 'linux')
+        return null; // the numbers below are Linux's; elsewhere, unknown = allowed
+    let probe = resolve(target);
+    while (!existsSync(probe) && dirname(probe) !== probe)
+        probe = dirname(probe);
+    let type;
+    try {
+        type = statfs(probe).type;
+    }
+    catch {
+        return null; // cannot tell: fail open, as for an unrecognised type
+    }
+    const name = NETWORK_FILESYSTEMS[type];
+    return name ? { name, probe, type } : null;
+}
+/**
+ * Throws, naming the path and the filesystem, when `databaseFile` would be opened on a network
+ * filesystem. A file that does not exist yet is judged by the nearest directory that does, since
+ * that is where SQLite will create it.
+ */
+export function refuseNetworkFilesystem(databaseFile, statfs = (p) => statfsSync(p), platform = process.platform) {
+    const found = networkFilesystemAt(databaseFile, statfs, platform);
+    if (found) {
+        throw new Error(`refusing to start: the SQLite database ${databaseFile} would live on ${found.name} (${found.probe}, filesystem type 0x${found.type.toString(16)}). ` +
+            'SQLite in WAL mode needs shared memory, which network filesystems do not provide — the database would fail to open or corrupt. ' +
+            'Put the data directory (FAST_STORAGE) on local disk; backups may still go to the NAS (#1536).');
+    }
+}

package/lib/src/providers/sqliteMigrations.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Schema migrations — dated, run-once, recorded, transactional. Ported from yourPHR (yourphr#542),
+ * where it runs in production; ngdpbase #1536. A migration is a FROZEN SNAPSHOT of intent at its
+ * date — it never references live code, because the live code moves on and the migration must keep
+ * describing what it did the day it ran.
+ *
+ * Two rules yourPHR paid to learn, made structural here:
+ *
+ *   - yourphr#528: ADD COLUMN leaves every EXISTING row NULL, not zero — and NULL + 1 is NULL, so
+ *     a revocation counter "incremented" for months without moving, reporting success throughout.
+ *     addColumnWithDefault() is the required spelling for counter-like columns: default for new
+ *     rows, explicit backfill for existing ones, in the same migration.
+ *   - Downgrade protection: a database that records a migration THIS build has never heard of is a
+ *     database from the future, and opening it "best effort" is how schema corruption happens.
+ *     Refuse to start instead.
+ *
+ * No down() — deliberately: the rollback story is a backup taken before anything migrates, not a
+ * reverse script that was never tested against real data.
+ */
+import type Database from 'better-sqlite3-multiple-ciphers';
+export interface Migration {
+    /** Dated, sortable: YYYYMMDDHHMMSS. The registry must be strictly ascending. */
+    id: string;
+    description: string;
+    up: (db: InstanceType<typeof Database>) => void;
+}
+export interface MigrationReport {
+    applied: string[];
+    skipped: number;
+}
+/**
+ * ADD COLUMN with a default AND a backfill of existing rows, in one statement pair — the yourphr#528
+ * spelling. SQLite's ADD COLUMN ... DEFAULT only applies the default to rows created afterwards
+ * on some historic versions and to reads via the schema on others; the explicit UPDATE removes
+ * the ambiguity for every row that already exists.
+ */
+export declare function addColumnWithDefault(db: InstanceType<typeof Database>, table: string, column: string, type: 'INTEGER' | 'TEXT' | 'REAL', defaultValue: number | string): void;
+/**
+ * Applies every pending migration, in order, each in its own transaction. Stops loudly at the
+ * first failure, leaving everything before it applied and everything from it untouched — a rerun
+ * after the fix picks up exactly there.
+ */
+/**
+ * `ledgerTable` names the table the applied ids are recorded in. A second database keeps its own
+ * name (yourphr#784): a backup holding several databases' tables in one file splits them back BY
+ * TABLE NAME on restore, and two tables called schema_migrations could not be told apart.
+ */
+export declare function runMigrations(db: InstanceType<typeof Database>, registry: Migration[], ledgerTable?: string): MigrationReport;

package/lib/src/providers/sqliteMigrations.js

@@ -0,0 +1,72 @@
+const ID_SHAPE = /^\d{14}$/;
+/**
+ * ADD COLUMN with a default AND a backfill of existing rows, in one statement pair — the yourphr#528
+ * spelling. SQLite's ADD COLUMN ... DEFAULT only applies the default to rows created afterwards
+ * on some historic versions and to reads via the schema on others; the explicit UPDATE removes
+ * the ambiguity for every row that already exists.
+ */
+export function addColumnWithDefault(db, table, column, type, defaultValue) {
+    const quoted = typeof defaultValue === 'string' ? `'${defaultValue.replace(/'/g, "''")}'` : String(defaultValue);
+    db.exec(`ALTER TABLE "${table}" ADD COLUMN "${column}" ${type} NOT NULL DEFAULT ${quoted}`);
+    db.exec(`UPDATE "${table}" SET "${column}" = ${quoted} WHERE "${column}" IS NULL`);
+}
+/**
+ * Applies every pending migration, in order, each in its own transaction. Stops loudly at the
+ * first failure, leaving everything before it applied and everything from it untouched — a rerun
+ * after the fix picks up exactly there.
+ */
+/**
+ * `ledgerTable` names the table the applied ids are recorded in. A second database keeps its own
+ * name (yourphr#784): a backup holding several databases' tables in one file splits them back BY
+ * TABLE NAME on restore, and two tables called schema_migrations could not be told apart.
+ */
+export function runMigrations(db, registry, ledgerTable = 'schema_migrations') {
+    // Digits are allowed after the first letter: an add-on slug may carry them ('calendar2'), and its
+    // ledger is named after the slug (ngdp-accounting-addons#13).
+    if (!/^[a-z][a-z0-9_]*$/.test(ledgerTable))
+        throw new Error(`migration ledger table ${ledgerTable} is not a plain name`);
+    // Registry hygiene before anything touches the database.
+    let previous = '';
+    for (const m of registry) {
+        if (!ID_SHAPE.test(m.id)) {
+            throw new Error(`migration id ${m.id} is not YYYYMMDDHHMMSS`);
+        }
+        if (m.id <= previous) {
+            throw new Error(`migration ids must be strictly ascending: ${m.id} follows ${previous}`);
+        }
+        previous = m.id;
+    }
+    db.exec(`CREATE TABLE IF NOT EXISTS ${ledgerTable} (
+    id TEXT PRIMARY KEY,
+    description TEXT NOT NULL,
+    applied_at TEXT NOT NULL
+  )`);
+    // Downgrade protection: an applied id the registry does not know means the database belongs to a
+    // NEWER build. Opening it anyway is how corruption happens — refuse, name the ids.
+    const appliedIds = new Set(db.prepare(`SELECT id FROM ${ledgerTable}`).all().map((r) => r.id));
+    const known = new Set(registry.map((m) => m.id));
+    const fromTheFuture = [...appliedIds].filter((id) => !known.has(id));
+    if (fromTheFuture.length > 0) {
+        throw new Error(`database schema is newer than this build — applied migrations this build does not know: ${fromTheFuture.sort().join(', ')}. Refusing to start; upgrade the app or restore the matching backup.`);
+    }
+    const report = { applied: [], skipped: 0 };
+    for (const migration of registry) {
+        if (appliedIds.has(migration.id)) {
+            report.skipped++;
+            continue;
+        }
+        db.exec('BEGIN');
+        try {
+            migration.up(db);
+            db.prepare(`INSERT INTO ${ledgerTable} (id, description, applied_at) VALUES (?, ?, ?)`).run(migration.id, migration.description, new Date().toISOString());
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            db.exec('ROLLBACK');
+            // The id in the error is what makes a 2am failure debuggable from the log line alone.
+            throw new Error(`migration ${migration.id} (${migration.description}) failed and was rolled back: ${err.message}`, { cause: err });
+        }
+        report.applied.push(migration.id);
+    }
+    return report;
+}

package/lib/src/rendering/githubAlerts.d.ts

@@ -0,0 +1,22 @@
+/**
+ * GitHub alerts (#1493): a blockquote whose first line is exactly `[!NOTE]`,
+ * `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]` renders in GitHub's
+ * own shape, stored as written:
+ *
+ *   <div class="markdown-alert markdown-alert-note">
+ *     <p class="markdown-alert-title"><svg …/>Note</p>
+ *     …the rest of the quote…
+ *   </div>
+ *
+ * Written here rather than taken from `markdown-it-github-alerts`: that plugin
+ * reads any text after the marker as a custom title and writes it into the
+ * page unescaped, which would let `> [!NOTE] <img onerror=…>` past the HTML
+ * policy (#1623). GitHub itself does not make an alert of a marker with text
+ * after it on the same line, and neither does this rule. Titles are fixed.
+ *
+ * Icons: GitHub's Octicons (info, light-bulb, report, alert, stop), MIT
+ * licensed, https://github.com/primer/octicons.
+ */
+import type MarkdownIt from 'markdown-it';
+/** Turn qualifying blockquotes into GitHub alerts. */
+export declare function githubAlerts(md: MarkdownIt): void;

package/lib/src/rendering/htmlPolicy.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The one HTML policy for page content (#1623).
+ *
+ * Raw HTML an author writes in a page is held to one allow-list, declared once
+ * in configuration (`ngdpbase.markup.html-policy`) and enforced here by one
+ * parser — sanitize-html, built on htmlparser2. Save and render ask the same
+ * question of the same code:
+ *
+ *   - render: {@link filterAuthorHtml} rewrites each piece of author HTML,
+ *     keeping what the policy allows and dropping the rest. It runs inside
+ *     markdown-it's `html_block` / `html_inline` renderers
+ *     (src/rendering/markdownConverter.ts), so it sees author HTML and nothing
+ *     else: plugin, link and variable output is merged in after markdown-it,
+ *     from placeholders, and is never seen by it.
+ *   - save: {@link htmlPolicyViolations} names what that rewrite would drop,
+ *     and SecurityFilter refuses the save with those names.
+ *
+ * Why per tag, not per fragment: markdown-it hands author HTML over in pieces —
+ * `<div>` and `</div>` arrive as separate tokens around the markdown between
+ * them, and inline HTML arrives one tag per token. A tree sanitiser given a
+ * piece balances it (`<div>` becomes `<div></div>`) and drops a close it never
+ * saw opened, which would break every page that wraps markdown in HTML. So each
+ * piece is split into tags and text with markdown-it's own HTML tag grammar,
+ * each open tag is rebuilt by sanitize-html from its parsed attributes, a close
+ * tag stays if its tag is allowed, and text is escaped.
+ *
+ * Why that is safe whatever the grammar's edge cases: everything not taken as
+ * a tag is escaped (`<` becomes `&lt;`), so the browser cannot find a tag in it;
+ * everything taken as a tag is re-serialised by sanitize-html from what
+ * htmlparser2 parsed; comments, declarations and processing instructions are
+ * dropped. A disagreement between the grammar and a browser can only turn
+ * markup into visible text, never text into markup.
+ *
+ * Without a policy (no ConfigurationManager, or a malformed value) nothing an
+ * author wrote is allowed: the failure is closed. The pipeline's own
+ * constructs ({@link PIPELINE_HTML}) are always allowed.
+ *
+ * @module rendering/htmlPolicy
+ */
+/** The configuration key that declares the policy. */
+export declare const HTML_POLICY_KEY = "ngdpbase.markup.html-policy";
+/**
+ * The policy, read from configuration. There each list is a set kept as a map
+ * of `name: true` (#1612), so a layer adds or removes one entry without
+ * restating the rest; here it is the enabled names.
+ */
+export interface HtmlPolicy {
+    /** Tags an author may write. */
+    tags: string[];
+    /** Attributes allowed per tag; `*` applies to every allowed tag. */
+    attributes: Record<string, string[]>;
+    /** URL schemes allowed in URL attributes (`href`, `src`, …). Relative URLs are always allowed. */
+    schemes: string[];
+    /** A tag's own scheme set, used instead of `schemes` for that tag (`schemes-by-tag`). */
+    schemesByTag: Record<string, string[]>;
+}
+/**
+ * The configured value of `ngdpbase.markup.html-policy` as a policy, or null
+ * when it is absent or not an object — which allows no author HTML at all.
+ */
+export declare function asHtmlPolicy(value: unknown): HtmlPolicy | null;
+/**
+ * Author HTML as the policy allows it. `html` is one piece of author HTML —
+ * an html_block or html_inline token's content, or a raw block's text.
+ */
+export declare function filterAuthorHtml(html: string, policy: HtmlPolicy | null): string;
+/** One thing the policy does not allow, at an offset into the fragment. */
+export interface HtmlPolicyViolation {
+    message: string;
+    offset: number;
+}
+/**
+ * What {@link filterAuthorHtml} would drop from `html`, named for the author.
+ * Empty when the policy allows all of it.
+ */
+export declare function htmlPolicyViolations(html: string, policy: HtmlPolicy | null): HtmlPolicyViolation[];

package/lib/src/rendering/markdownConverter.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The one place that says how markdown becomes HTML (#1273, epic #1271).
+ *
+ * markdown-it replaces showdown, which has had no release since 2023 and whose
+ * mitigations (#599, #1064) were ours to keep correct on a dead parser; it was
+ * removed in #1274. Every option here was measured on the real page corpus by
+ * the #1272 harness (since retired), and each deliberate difference from
+ * showdown is a decision on the #1271 log (R2–R17), pinned by
+ * `__tests__/markdownConverter.test.ts`.
+ *
+ * Three profiles, not one shared configuration (R3) — the call sites differed
+ * under showdown, and merging them would silently change their HTML:
+ *
+ *   - `page`: page bodies, through MarkupParser. Single-newline breaks, heading
+ *     ids from `SectionUtils.headingSlug`, sub/superscript, task lists.
+ *   - `untrusted`: comments (`renderUntrustedInline`). Breaks, tables, fences
+ *     and `<del>`; no heading ids, task lists or sub/superscript — the showdown
+ *     converter it replaces had none of them.
+ *   - `fallback`: degraded paths that run without the page pipeline. Plain
+ *     CommonMark.
+ *
+ * The converter object keeps showdown's `makeHtml` shape, so a call site
+ * changes its constructor and nothing else.
+ *
+ * Author HTML (#1623): in the `page` and `fallback` profiles, every html_block
+ * and html_inline token markdown-it parses out of the source — the HTML an
+ * author wrote — is rewritten by the one HTML policy
+ * (src/rendering/htmlPolicy.ts) as it renders. Those two token types are the
+ * only way raw HTML leaves markdown-it, so nothing else needs guarding here. The policy is read at render time from whoever made the
+ * converter, so a change in configuration applies without a restart; with no
+ * reader, no author HTML is allowed. `untrusted` keeps its own sanitiser
+ * (src/utils/renderUntrustedInline.ts).
+ *
+ * @module rendering/markdownConverter
+ */
+import MarkdownIt from 'markdown-it';
+export type MarkdownProfile = 'page' | 'untrusted' | 'fallback';
+/** showdown's converter shape, kept so call sites swap without rewriting. */
+export interface MarkdownConverter {
+    makeHtml(markdown: string): string;
+}
+/**
+ * A markdown-it instance for one profile. Exported for the option tests; app
+ * code uses {@link createMarkdownConverter}.
+ */
+export declare function buildMarkdownIt(profile: MarkdownProfile): MarkdownIt;
+/**
+ * Inline Markdown for one line of text that is not a paragraph: a table cell
+ * (#1351). The page profile's inline rules — `**bold**`, `*italic*`,
+ * `~~strike~~`, `~sub~`, `^sup^`, `` `code` ``, `[text](url)` — with HTML
+ * escaped rather than passed through, which is what a cell has always done.
+ * No block rules and no paragraph: `renderInline`.
+ */
+export declare function renderInlineMarkdown(text: string): string;
+/**
+ * The converter for a profile. `readHtmlPolicy` returns the configured value of
+ * `ngdpbase.markup.html-policy` and is called on every render, so the policy in
+ * force is always the configured one; without it, no author HTML is allowed.
+ * One markdown-it instance per profile; renders are independent.
+ */
+export declare function createMarkdownConverter(profile: MarkdownProfile, readHtmlPolicy?: () => unknown): MarkdownConverter;
+/** A piece of author HTML in page source, and the 0-based line it starts on. */
+export interface AuthorHtml {
+    html: string;
+    line: number;
+}
+/**
+ * The author HTML in page source, found exactly as the page profile finds it
+ * when rendering: the html_block and html_inline tokens. Code blocks and code
+ * spans are code to markdown-it, so they are not here. The save-time check
+ * (SecurityFilter) holds these to the policy the renderer applies (#1623).
+ */
+export declare function authorHtmlIn(markdown: string): AuthorHtml[];