@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/shared/recordview.js

@@ -0,0 +1,356 @@
+/**
+ * A record template: one row, with its references pulled in around it.
+ *
+ * The view composer as built answers "give me a table of X with columns from
+ * the things X points at" — one row per base record, joins flattened into
+ * columns. That is a useful shape and the wrong one for the question tablewalk
+ * actually exists to answer, which is "show me *this* work order, properly".
+ *
+ * That question wants a page: the work order's own fields, the customer's
+ * details inline because a work order without its customer's name is a
+ * riddle, and its parts and notes as tables underneath because there are
+ * several of each and a count is not enough.
+ *
+ * The difference from a list view is not cosmetic — it is what the thing is
+ * bound to. A list view is a *query*: it produces rows and you read them. A
+ * record template is bound to a **table**, not to a row, and applies to every
+ * row of it. Configure `work_order` once and every work order you ever walk
+ * to is laid out that way. That is what makes it worth configuring at all.
+ *
+ * Two consequences fall out, and both are why this shape earns its place:
+ *
+ *   - A has-many relationship is finally answerable. In a list view it either
+ *     multiplies rows or collapses to a count; here it is simply a table on
+ *     the page, which is what anyone asking for "the order and its lines"
+ *     meant in the first place.
+ *   - Views stop being a dead end. A list view is somewhere you look; a
+ *     record template is where a walk *arrives*, so views become part of the
+ *     navigation rather than a parallel product beside it.
+ */
+import { findTable, labelColumn, looksLikeDate, primaryKey, referencesFrom, referencesTo, } from './schema.js';
+import { parseSortText } from './sortText.js';
+/** Rows to show in an embedded list before it needs its own page. */
+export const DEFAULT_LIST_LIMIT = 10;
+/**
+ * Below this many columns, grouping costs more than it saves.
+ *
+ * A four-column table split into "Identity" and "Details" is two headings and
+ * a divider to organise four fields — more ceremony than content, and slower
+ * to read than the flat list it replaced.
+ */
+const GROUP_THRESHOLD = 12;
+const AUDIT_NAME = /^(sys_|created|updated|modified|deleted|inserted)|_(at|by)$|^(version|etag|revision)$/i;
+/**
+ * How a table's own columns divide into blocks.
+ *
+ * Derived from what the schema already says rather than from a stored layout:
+ * keys and the label column identify, foreign keys link, dates measure, and
+ * anything named like an audit column is bookkeeping. Ordering is by what
+ * gets looked at first, not by declaration order.
+ *
+ * Lives here rather than in the renderer because it *is* the default
+ * template. Having the derivation in one place and the stored layout in
+ * another is how the two start disagreeing about what a record looks like.
+ */
+export function groupOwnColumns(table) {
+    const columns = table.columns;
+    if (columns.length < GROUP_THRESHOLD)
+        return [[null, columns]];
+    const label = labelColumn(table);
+    const groups = new Map([
+        ['Identity', []],
+        ['Bookkeeping', []],
+        ['References', []],
+        ['Details', []],
+        ['Dates', []],
+    ]);
+    for (const col of columns) {
+        if (col.primaryKey || col.name === label)
+            groups.get('Identity').push(col);
+        else if (col.references)
+            groups.get('References').push(col);
+        else if (AUDIT_NAME.test(col.name))
+            groups.get('Bookkeeping').push(col);
+        else if (looksLikeDate(col))
+            groups.get('Dates').push(col);
+        else
+            groups.get('Details').push(col);
+    }
+    // A section with nothing in it is a heading that means nothing.
+    return [...groups].filter(([, cols]) => cols.length);
+}
+/* ---------- deriving a starting template ---------- */
+/**
+ * The template a table gets before anyone configures one.
+ *
+ * Derived rather than blank, because a blank record page is a worse starting
+ * point than the default layout the record view already produces, and because
+ * the fastest way to explain what a template *is* is to show someone one made
+ * of their own data.
+ *
+ * The rules are the ones the record view already uses, made explicit: the
+ * record's own fields first, then each to-one reference as its own labelled
+ * block, then each incoming relationship as a table.
+ */
+export function deriveTemplate(schema, tableId) {
+    const table = findTable(schema, tableId);
+    if (!table)
+        return undefined;
+    const sections = groupOwnColumns(table).map(([title, columns]) => ({
+        kind: 'fields',
+        title: title ?? undefined,
+        paths: columns.map((c) => c.name),
+    }));
+    /* One block per outgoing reference, holding a few readable columns of the
+       row it points at. Not every column: pulling a customer's forty fields
+       into a work order buries the work order. */
+    for (const fk of referencesFrom(schema, tableId)) {
+        if (fk.to.table === tableId)
+            continue; // a self-reference adds no context
+        const target = findTable(schema, fk.to.table);
+        if (!target)
+            continue;
+        const via = fk.from.columns.join('+');
+        sections.push({
+            kind: 'fields',
+            title: `${target.name} · via ${fk.from.columns.join(', ')}`,
+            paths: summaryColumns(target).map((c) => `${via}.${c}`),
+        });
+    }
+    for (const fk of referencesTo(schema, tableId)) {
+        const child = findTable(schema, fk.from.table);
+        if (!child)
+            continue;
+        sections.push({
+            kind: 'list',
+            title: `${child.name} · via ${fk.from.columns.join(', ')}`,
+            via: fk.name,
+            columns: listColumns(child, fk.from.columns),
+            limit: DEFAULT_LIST_LIMIT,
+        });
+    }
+    return { id: `derived:${tableId}`, name: table.name, base: tableId, sections };
+}
+/**
+ * Every column of a child table worth showing, in declaration order.
+ *
+ * All of them, not a summary. A summary is the right shape for a reference
+ * pulled *into* a record — a customer's forty fields would bury the work order
+ * they are attached to — and the wrong shape for a table of children, which is
+ * the thing you opened the record to read. `work_order_part` summarised down
+ * to one column of quantities is a list of numbers with nothing to attach them
+ * to.
+ *
+ * The join columns are still dropped: every row here carries the same value
+ * for them, so a column of one repeated value is width spent on nothing. The
+ * key stays, because it is what distinguishes the rows.
+ *
+ * Anyone who wants fewer can say so in the layout builder, which is the right
+ * order for a default — start from everything and subtract, rather than start
+ * from a guess and hunt for what is missing.
+ */
+export function listColumns(table, exclude = []) {
+    const skip = new Set(exclude);
+    const chosen = table.columns.filter((c) => !skip.has(c.name)).map((c) => c.name);
+    // Everything was part of the join: the key is better than an empty table.
+    return chosen.length ? chosen : primaryKey(table).slice(0, 1);
+}
+/**
+ * A few columns that say what a row *is*.
+ *
+ * Keys and the columns forming the join are dropped: in a table of a work
+ * order's parts, every row has the same `work_order_id`, so a column of it is
+ * a column of one repeated value. What is left is what distinguishes the rows
+ * from each other, which is the only thing the section is there to show.
+ */
+export function summaryColumns(table, exclude = [], max = 5) {
+    const skip = new Set(exclude);
+    const chosen = [];
+    for (const column of table.columns) {
+        if (skip.has(column.name))
+            continue;
+        if (column.primaryKey && table.columns.some((c) => !c.primaryKey && !skip.has(c.name)))
+            continue;
+        chosen.push(column.name);
+        if (chosen.length >= max)
+            break;
+    }
+    // Everything was a key or excluded: the key is better than nothing.
+    return chosen.length ? chosen : primaryKey(table).slice(0, 1);
+}
+/**
+ * Match each list section to the foreign key it names.
+ *
+ * A section whose constraint has since been dropped is returned as an error
+ * rather than skipped: a template that quietly stops showing a table looks
+ * exactly like a record that has no rows in it.
+ */
+export function resolveLists(schema, template) {
+    const lists = [];
+    const errors = [];
+    for (const section of template.sections) {
+        if (section.kind !== 'list')
+            continue;
+        const fk = referencesTo(schema, template.base).find((f) => f.name === section.via);
+        if (!fk) {
+            errors.push(`${template.name}: nothing called "${section.via}" points at ${template.base} any more. ` +
+                `The section was left in place so it can be removed or repointed.`);
+            continue;
+        }
+        const child = findTable(schema, fk.from.table);
+        if (!child) {
+            errors.push(`${template.name}: ${fk.from.table} is not in this schema.`);
+            continue;
+        }
+        lists.push({
+            section,
+            fk,
+            child,
+            join: fk.to.columns.map((parentColumn, i) => ({
+                parentColumn,
+                childColumn: fk.from.columns[i] ?? fk.from.columns[0],
+            })),
+        });
+    }
+    return { lists, errors };
+}
+/**
+ * Every path the base row itself has to supply.
+ *
+ * Collected across field sections so the record can be fetched in one query
+ * rather than one per section — a page with six reference blocks should not
+ * be six round trips.
+ */
+export function fieldPaths(template) {
+    const seen = new Set();
+    for (const section of template.sections) {
+        if (section.kind !== 'fields')
+            continue;
+        for (const path of section.paths)
+            seen.add(path);
+    }
+    return [...seen];
+}
+/** Whether a template still says anything, after resolution. */
+export function isEmpty(template) {
+    return !template.sections.some((s) => (s.kind === 'list' ? true : s.paths.length > 0));
+}
+/* The spellings a layout section may not use any more, each mapped to the
+   word that replaced it. Refused by name, in the parser's usual voice, the
+   same way parseSection in page.ts refuses them — a local copy rather than a
+   shared helper, because the two parsers name different examples and the
+   client mirror rules keep this file importing nothing it does not need.
+   `via` is NOT here: it names the foreign key's constraint, which is a
+   different fact from the direction `whose` writes down, and it keeps its
+   name. */
+const RENAMED = {
+    path: '"whose" — the column of the child table that names this record, e.g. "customer_id"',
+    paths: '"show" — the fields to show, e.g. ["name", "customer_id.name"]',
+    columns: '"show" — the columns the list shows, e.g. ["invoice_date", "total"]',
+    orderBy: '"sort" — written like the query bar, e.g. "invoice_date desc, id"',
+};
+function refuseRenamed(s, at, keys) {
+    for (const key of keys) {
+        if (s[key] !== undefined)
+            throw new Error(`${at} has "${key}", which is now ${RENAMED[key]}.`);
+    }
+}
+function parseSort(raw, at) {
+    return parseSortText(raw, at, 'invoice_date desc, id');
+}
+/**
+ * Read the `layouts` section of a tablewalk.json.
+ *
+ * Throws on anything malformed rather than skipping it, naming the entry and
+ * the fix — the same rule `parsePagesConfig` follows, for the same reason: a
+ * layout that silently did not appear is a bug report that starts "I
+ * definitely wrote it".
+ *
+ * Structure only. Whether `customer_id` is a real column, or `invoice` a real
+ * table, needs a schema this runs long before — those are answered when the
+ * layout is served, and reported on the layout itself.
+ */
+export function parseLayoutsConfig(raw, where) {
+    const layouts = raw?.layouts;
+    if (layouts === undefined)
+        return [];
+    if (!Array.isArray(layouts))
+        throw new Error(`${where}: "layouts" must be an array.`);
+    const seen = new Set();
+    return layouts.map((entry, i) => {
+        const at = `${where}: layout ${i + 1}`;
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw new Error(`${at} is not an object.`);
+        }
+        const l = entry;
+        if (typeof l.table !== 'string' || !l.table.trim()) {
+            throw new Error(`${at} has no "table" — a layout lays out one table's records.`);
+        }
+        const table = l.table.trim();
+        if (l.connection !== undefined && typeof l.connection !== 'string') {
+            throw new Error(`${at} ("${table}") has a "connection" that is not a string.`);
+        }
+        if (l.name !== undefined && typeof l.name !== 'string') {
+            throw new Error(`${at} ("${table}") has a "name" that is not a string.`);
+        }
+        /* One per table per connection: the store this fills is keyed that way,
+           so a second would silently win over the first. */
+        const key = `${l.connection ?? ''}::${table}`;
+        if (seen.has(key))
+            throw new Error(`${at} repeats a layout for "${table}".`);
+        seen.add(key);
+        if (!Array.isArray(l.sections) || !l.sections.length) {
+            throw new Error(`${at} ("${table}") has no "sections".`);
+        }
+        const sections = l.sections.map((raw2, j) => {
+            const sat = `${at} ("${table}"), section ${j + 1}`;
+            if (!raw2 || typeof raw2 !== 'object' || Array.isArray(raw2)) {
+                throw new Error(`${sat} is not an object.`);
+            }
+            const s = raw2;
+            if (s.kind !== 'fields' && s.kind !== 'list') {
+                throw new Error(`${sat} has "kind": ${JSON.stringify(s.kind)} — it must be "fields" or "list".`);
+            }
+            if (s.title !== undefined && typeof s.title !== 'string') {
+                throw new Error(`${sat} has a "title" that is not a string.`);
+            }
+            if (s.kind === 'fields') {
+                refuseRenamed(s, sat, ['paths']);
+                if (!Array.isArray(s.show) || !s.show.every((p) => typeof p === 'string' && p.trim())) {
+                    throw new Error(`${sat} needs "show": a list of column names or paths like customer_id.name.`);
+                }
+                return { kind: 'fields', ...(s.title ? { title: s.title } : {}), paths: s.show.map((p) => String(p).trim()) };
+            }
+            /* A list says which relationship it shows, one way or the other. */
+            refuseRenamed(s, sat, ['path', 'columns', 'orderBy']);
+            const hasVia = typeof s.via === 'string' && s.via.trim();
+            const hasPair = typeof s.from === 'string' && s.from.trim() && typeof s.whose === 'string' && s.whose.trim();
+            if (!hasVia && !hasPair) {
+                throw new Error(`${sat} needs either "via" (a foreign key constraint name) or "from" and "whose" ` +
+                    `— the child table and the column of it that points back here.`);
+            }
+            if (s.show !== undefined && (!Array.isArray(s.show) || !s.show.every((c) => typeof c === 'string'))) {
+                throw new Error(`${sat} has a "show" that is not a list of column names.`);
+            }
+            if (s.limit !== undefined && (typeof s.limit !== 'number' || !Number.isInteger(s.limit) || s.limit < 1)) {
+                throw new Error(`${sat} has a "limit" that is not a whole number of rows.`);
+            }
+            const orderBy = parseSort(s.sort, sat);
+            return {
+                kind: 'list',
+                ...(s.title ? { title: s.title } : {}),
+                ...(hasVia ? { via: String(s.via).trim() } : {}),
+                ...(hasPair ? { from: String(s.from).trim(), path: String(s.whose).trim() } : {}),
+                columns: Array.isArray(s.show) ? s.show.map((c) => String(c)) : [],
+                ...(s.limit !== undefined ? { limit: s.limit } : {}),
+                ...(orderBy !== undefined ? { orderBy } : {}),
+            };
+        });
+        return {
+            table,
+            ...(l.connection ? { connection: String(l.connection) } : {}),
+            ...(l.name ? { name: String(l.name) } : {}),
+            sections,
+        };
+    });
+}

package/dist/shared/referenceModel.d.ts

@@ -0,0 +1,58 @@
+/** Reference paths and joined labels used when planning record and view reads. */
+import { type DatabaseSchema, type TableMeta } from './schema.js';
+/** Joined labels share the field query; never fetch each reference separately. */
+export declare function referenceProjection(schema: DatabaseSchema, table: TableMeta, paths: readonly string[], enabled: boolean, namingPath?: (table: TableMeta) => string | undefined): {
+    fetched: string[];
+    labels: Map<string, string>;
+};
+/** Hidden label columns must not replace raw keys or collide with authored aliases. */
+export declare function referenceView<T extends {
+    columns?: Array<{
+        path: string;
+        alias?: string;
+    }>;
+}>(schema: DatabaseSchema, table: TableMeta, view: T, enabled: boolean, namingPath?: (table: TableMeta) => string | undefined): {
+    view: T;
+    labelColumns: Record<string, string>;
+    hidden: string[];
+};
+/** Navigation needs the complete authorized key, independently of authored show.
+ * Add labels first so hidden key columns do not introduce extra reference labels. */
+export declare function recordView<T extends {
+    columns?: Array<{
+        path: string;
+        alias?: string;
+    }>;
+}>(schema: DatabaseSchema, table: TableMeta, view: T, enabled: boolean, namingPath?: (table: TableMeta) => string | undefined, rootLabelPath?: (table: TableMeta) => string | undefined): {
+    labelColumns: Record<string, string>;
+    view: T & {
+        columns: {
+            path: string;
+            alias?: string;
+        }[];
+    };
+    hidden: string[];
+    keyColumns: {
+        column: string;
+        index: number;
+    }[];
+    labelColumn: {
+        path: string;
+        index: number;
+    } | undefined;
+};
+/** A private synthetic output is the only value record navigation may treat as
+ * the configured label. It deliberately does not copy or rename authored cells. */
+export declare function recordViewLabel(labelColumn: {
+    path: string;
+    index: number;
+} | undefined, outputs: readonly string[], row: Record<string, unknown>): Record<string, unknown>;
+/** Returned output positions preserve aliases without narrowing numeric strings. */
+export declare function recordViewKey(keyColumns: readonly {
+    column: string;
+    index: number;
+}[], outputs: readonly string[], row: Record<string, unknown>): Record<string, string | number> | null;
+/** A name that opens with the page record's, said without it. */
+export declare function withoutParent<T>(value: T, parent: string | undefined): T | string;
+/** The rows with every label that opens with the page record's name said without it. */
+export declare function withoutParentName(rows: ReadonlyArray<Record<string, unknown>>, labelOutputs: readonly string[], parent: string | undefined): Array<Record<string, unknown>>;

package/dist/shared/referenceModel.js

@@ -0,0 +1,194 @@
+/** Reference paths and joined labels used when planning record and view reads. */
+import { findTable, labelColumn, primaryKey } from './schema.js';
+import { rollupColumnMeta } from './rollups.js';
+import { MAX_PATH_DEPTH, tryResolvePath } from './viewPaths.js';
+function viewOutputs(columns) {
+    const counts = new Map();
+    return columns.map((col) => {
+        const name = col.alias?.trim() || col.path;
+        const count = (counts.get(name) ?? 0) + 1;
+        counts.set(name, count);
+        return count === 1 ? name : `${name}_${count}`;
+    });
+}
+/** Joined labels share the field query; never fetch each reference separately. */
+export function referenceProjection(schema, table, paths, enabled, namingPath = labelColumn) {
+    const fetched = [...new Set(paths)];
+    const labels = new Map();
+    if (!enabled)
+        return { fetched, labels };
+    /* A single column cannot safely traverse one leg of a composite foreign
+       key — unless it is also a key of its own: a tenant's `vehicle_id` is both
+       the composite `(tenant_id, vehicle_id)`, which keeps it in its tenant, and
+       the single key its path walks, and was drawn as its opaque id. */
+    const composite = (tableId) => {
+        const single = new Set(schema.foreignKeys.filter((fk) => fk.from.table === tableId && fk.from.columns.length === 1).map((fk) => fk.from.columns[0]));
+        return new Set(schema.foreignKeys
+            .filter((fk) => fk.from.table === tableId && fk.from.columns.length > 1)
+            .flatMap((fk) => fk.from.columns)
+            .filter((column) => !single.has(column)));
+    };
+    for (const path of paths) {
+        /* A reference reached through others — `employee_id.department_id` —
+           is named the same way as one on the row itself: its record's label,
+           read one hop further along, while the path stays within reach. */
+        let column;
+        let owner = table.id;
+        let hops = 0;
+        let derived = false;
+        if (!path.includes('.')) {
+            column = table.columns.find((col) => col.name === path);
+            /* A latest of a reference column is the record's key too (rollups.ts): named as the column it reads is, by a
+               column of that record (`resident.name`, viewPaths.ts); a template or a path past it is not a column to read. */
+            const rollup = !column && table.rollups && Object.hasOwn(table.rollups, path) ? table.rollups[path] : undefined;
+            if (rollup?.fn === 'latest' && rollup.references && !rollup.of) {
+                column = rollupColumnMeta(path, rollup);
+                derived = true;
+            }
+        }
+        else {
+            const { resolved } = tryResolvePath(schema, table.id, path);
+            if (!resolved)
+                continue;
+            column = resolved.column;
+            owner = resolved.table.id;
+            hops = resolved.hops.length;
+        }
+        if (!column?.references || composite(owner).has(column.name))
+            continue;
+        const target = findTable(schema, column.references.table);
+        const naming = target && namingPath(target);
+        if (derived && (!naming || naming.includes('.') || !target?.columns.some((col) => col.name === naming)))
+            continue;
+        if (!naming || hops + 1 + naming.split('.').length - 1 > MAX_PATH_DEPTH)
+            continue;
+        const labelAt = `${path}.${naming}`;
+        labels.set(path, labelAt);
+        if (!fetched.includes(labelAt))
+            fetched.push(labelAt);
+    }
+    return { fetched, labels };
+}
+/** Hidden label columns must not replace raw keys or collide with authored aliases. */
+export function referenceView(schema, table, view, enabled, namingPath = labelColumn) {
+    const columns = view.columns ?? [];
+    const projection = referenceProjection(schema, table, columns.map((col) => col.path), enabled, namingPath);
+    const labelColumns = {};
+    const hidden = [];
+    const outputs = viewOutputs(columns);
+    const used = new Set(outputs);
+    const extra = [];
+    columns.forEach((col, index) => {
+        const label = projection.labels.get(col.path);
+        if (!label)
+            return;
+        let alias = `__tw_reference_${index}`;
+        while (used.has(alias))
+            alias += '_';
+        used.add(alias);
+        extra.push({ path: label, alias });
+        labelColumns[outputs[index]] = alias;
+        hidden.push(alias);
+    });
+    return { view: extra.length ? { ...view, columns: [...columns, ...extra] } : view, labelColumns, hidden };
+}
+/** Navigation needs the complete authorized key, independently of authored show.
+ * Add labels first so hidden key columns do not introduce extra reference labels. */
+export function recordView(schema, table, view, enabled, namingPath = labelColumn, rootLabelPath) {
+    const shown = view.columns?.length ? view : { ...view, columns: table.columns.map((column) => ({ path: column.name })) };
+    const presentation = referenceView(schema, table, shown, enabled, namingPath);
+    const columns = [...(presentation.view.columns ?? [])];
+    const outputs = viewOutputs(columns);
+    const used = new Set(outputs);
+    const hidden = [...presentation.hidden];
+    // A record's configured label may be a joined path and the view may have
+    // named an unrelated column or alias the same way. Carry it in a private
+    // output so navigation never reads an authored cell as the record's name.
+    const naming = rootLabelPath?.(table);
+    let labelColumn;
+    if (naming) {
+        let alias = '__tw_label';
+        while (used.has(alias))
+            alias += '_';
+        used.add(alias);
+        labelColumn = { path: naming, index: columns.length };
+        columns.push({ path: naming, alias });
+        outputs.push(alias);
+        hidden.push(alias);
+    }
+    const keyColumns = primaryKey(table).map((column, keyIndex) => {
+        // A colliding authored output cannot be trusted to contain this path's value.
+        let index = columns.findIndex((col, i) => col.path === column && outputs.filter((name) => name === outputs[i]).length === 1);
+        if (index < 0) {
+            let alias = `__tw_key_${keyIndex}`;
+            while (used.has(alias))
+                alias += '_';
+            used.add(alias);
+            index = columns.length;
+            columns.push({ path: column, alias });
+            outputs.push(alias);
+            hidden.push(alias);
+        }
+        return { column, index };
+    });
+    return { ...presentation, view: { ...presentation.view, columns }, hidden, keyColumns, labelColumn };
+}
+/** A private synthetic output is the only value record navigation may treat as
+ * the configured label. It deliberately does not copy or rename authored cells. */
+export function recordViewLabel(labelColumn, outputs, row) {
+    if (!labelColumn)
+        return {};
+    const output = outputs[labelColumn.index];
+    if (output === undefined || outputs.filter((name) => name === output).length !== 1 || !Object.hasOwn(row, output))
+        return {};
+    return { [labelColumn.path]: row[output] };
+}
+/** Returned output positions preserve aliases without narrowing numeric strings. */
+export function recordViewKey(keyColumns, outputs, row) {
+    if (!keyColumns.length)
+        return null;
+    const entries = [];
+    for (const { column, index } of keyColumns) {
+        const output = outputs[index];
+        if (output === undefined || outputs.filter((name) => name === output).length !== 1 || !Object.hasOwn(row, output))
+            return null;
+        const value = row[output];
+        if (typeof value !== 'string' && (typeof value !== 'number' || !Number.isFinite(value)))
+            return null;
+        entries.push([column, value]);
+    }
+    return Object.fromEntries(entries);
+}
+/* A child is named by its parent and a word that tells it from its siblings
+   ("Ada Park · follow-up", docs/design.md). On the parent's own page every
+   sibling repeats the page's title, so the list says the word alone; a name
+   of some other parent, or one that is the parent's name and nothing more,
+   is left as it is. */
+const AFTER_PARENT = /^\s*[·•–—:|/-]\s*/u;
+/** A name that opens with the page record's, said without it. */
+export function withoutParent(value, parent) {
+    const name = parent?.trim();
+    if (!name || typeof value !== 'string' || !value.startsWith(name))
+        return value;
+    const rest = value.slice(name.length);
+    const cut = AFTER_PARENT.exec(rest);
+    const word = cut ? rest.slice(cut[0].length) : '';
+    return cut && word.trim() ? word : value;
+}
+/** The rows with every label that opens with the page record's name said without it. */
+export function withoutParentName(rows, labelOutputs, parent) {
+    if (!parent?.trim() || !labelOutputs.length)
+        return rows;
+    const trim = (value) => withoutParent(value, parent);
+    return rows.map((row) => {
+        let next;
+        for (const output of labelOutputs) {
+            if (!Object.hasOwn(row, output))
+                continue;
+            const said = trim(row[output]);
+            if (said !== row[output])
+                (next ??= { ...row })[output] = said;
+        }
+        return next ?? row;
+    });
+}

package/dist/shared/refusal.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A request an adapter will not carry out.
+ *
+ * Distinct from a database failure, and the distinction is the whole point:
+ * "that is not the whole primary key" and "the database is down" are both
+ * exceptions, and a server that cannot tell them apart answers both with a
+ * 500. The first is something the caller can fix by asking differently.
+ *
+ * Ordinary adapter guards run before a statement. Private scoped transactions
+ * also use this for stored-image checks: those failures poison the transaction
+ * and require rollback. The error class alone never proves a write outcome.
+ */
+export declare class Refusal extends Error {
+    /** The column names the message quotes, so a surface that calls them something else (an App's captions) can say them its way. Never values. */
+    readonly columns?: readonly string[];
+    /** `cause`: a database failure that kept the check from being made. The
+     * request is still refused — the boundary does not move — but an owner that
+     * answers a caller can tell "refused" from "could not answer". */
+    constructor(message: string, options?: {
+        columns?: readonly string[];
+        cause?: unknown;
+    });
+}
+/** Record why a refusal happened on the refusal itself, for the trusted reader
+ * only. Every opaque refusal takes its reason this way — a tenant denial, a
+ * row policy that did not load, a command the database would not take — so
+ * the one reader below can say it to the operator. A string is a sentence for
+ * that operator, written here and naming the rule, table or column. */
+export declare function recordRefusalCause<E extends object>(error: E, cause: unknown): E;
+/** The recorded reason behind a refusal, for a trusted diagnostic only. */
+export declare const refusalCause: (error: unknown) => unknown;
+/**
+ * What the operator is told about a refusal: each reason under it, outermost
+ * first — a recorded cause before `cause`, since the recorded one is the
+ * refusal's own — as messages, never objects, because a driver error's object
+ * can carry connection detail a console should not. Repeats are said once:
+ * a refusal rethrown as the same sentence is one reason, not two.
+ */
+export declare function refusalReasons(error: unknown): string[];
+/**
+ * The refusal's one line for a startup headline: the fixed sentence, then the
+ * reason behind it. The `because:` lines under it carry the whole chain, but a
+ * reader (or a log that keeps one line) stopped at "could not be loaded or is
+ * invalid" and went to bisect the module; the headline now says the cause.
+ */
+export declare function refusalHeadline(error: unknown): string;
+/** The `because:` lines under a refusalHeadline: the chain past the cause the headline says already, which
+    printed again beneath it read as two reasons. */
+export declare const refusalReasonsBelow: (error: unknown) => string[];
+/**
+ * A startup failure as the operator's terminal says it: the headline, then
+ * each further reason on a `because:` line. Every startup print goes through
+ * this, so a refusal that recorded why (a tenant denial's `"fonts" is not a
+ * key this takes`) is never said as its fixed sentence alone. The terminal of
+ * the person who started the server only: never an HTTP answer.
+ */
+export declare function startupReport(error: unknown): string;
+/** Where an unexpected fault in `error` (or the chain under it) happened: its first stack frames, or none for a refusal.
+    Read by name, not `instanceof`: an App module's errors are another realm's. */
+export declare function faultFrames(error: unknown, most?: number): string[];
+/** Record the sentence this refusal's caller is told: see above. The first one recorded stands. */
+export declare function sayRefusal<E extends object>(error: E, sentence: string): E;
+/** The sentence a refusal's caller may read about why, if the code that refused said one. */
+export declare const refusalSaid: (error: unknown) => string | undefined;