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

package/dist/shared/richText.js

@@ -0,0 +1,305 @@
+/**
+ * Rich text: what a stored value may hold, and its plain words.
+ *
+ * A rich text value is HTML, kept to one small allowlist — paragraphs and
+ * line breaks, bold, italic, strike and underline, links, three heading
+ * levels, bullet, numbered and task lists, a quote, inline code and a code
+ * block, simple tables, an @-mention, and a picture that is one of this App's
+ * own attachments. Nothing else: no style, no script, no event handler, no
+ * class but a code block's language.
+ *
+ * Two sides read this one list. The server writes nothing else
+ * (server/richText.ts, on every write of a rich text column or input), and
+ * the browser draws nothing else (components/RichText.tsx), whatever the
+ * database holds: a value written outside the App — by SQL, by another
+ * program, before the column was declared rich — is drawn through the same
+ * allowlist, never trusted for being in the database.
+ *
+ * The plain text twin is derived, never stored: `richTextPlain` reads the
+ * words out of a value, for a list cell's excerpt, a notice, a plain email
+ * and an export. A search of the column matches the stored HTML's words, so
+ * a word reads the same; a tag name is not a word anyone searches for.
+ */
+/** Where a rich text value is said in one line: a list cell, a card, a timeline row's excerpt. */
+const RICH_TEXT_EXCERPT = 160;
+/**
+ * A stored mention's handle (`data-id`): the value of the people's `by`
+ * column — a word, a number, a UUID, or an email. An email's `@` and `+` are
+ * in it: a people resource keyed by email was offered nobody, and a mention
+ * of one was dropped on save and never told.
+ */
+export const MENTION_HANDLE = /^[A-Za-z0-9_][A-Za-z0-9_.+@-]{0,253}$/;
+/** The most words after an @ that are each looked for (shared/mentionLookup.ts): "@Morgan Tr" narrows two Morgans,
+    and a space after the second word ends the name, so the list the editor offers closes there. */
+export const MENTION_QUERY_WORDS = 2;
+/** The most characters a rich text value holds, as stored HTML, unless its field says fewer. */
+export const RICH_TEXT_MOST = 200_000;
+/**
+ * The elements a value may hold, each with the attributes it keeps. An
+ * attribute's value is judged by `richTextAttribute` below.
+ */
+export const RICH_TEXT_ELEMENTS = Object.freeze({
+    p: [],
+    br: [],
+    strong: [],
+    b: [],
+    em: [],
+    i: [],
+    s: [],
+    u: [],
+    a: ['href'],
+    h2: [],
+    h3: [],
+    h4: [],
+    ul: ['data-type'],
+    ol: ['start'],
+    li: ['data-type', 'data-checked'],
+    blockquote: [],
+    code: ['class'],
+    pre: [],
+    table: [],
+    thead: [],
+    tbody: [],
+    tr: [],
+    th: ['colspan', 'rowspan'],
+    td: ['colspan', 'rowspan'],
+    span: ['data-type', 'data-id', 'data-kind'],
+    img: ['src', 'alt'],
+});
+/** Elements dropped with everything inside them: their content is code or chrome, never words. */
+export const RICH_TEXT_DROPPED = Object.freeze([
+    'script',
+    'style',
+    'template',
+    'iframe',
+    'object',
+    'embed',
+    'noscript',
+    'textarea',
+    'select',
+    'button',
+    'svg',
+    'math',
+    'head',
+    'title',
+]);
+/** A link's address: the web, or mail. Everything else (javascript:, data:, a relative path) is no link. */
+export function richTextHref(raw) {
+    const value = raw.trim();
+    if (!value || value.length > 2048 || /[\s\p{Cc}]/u.test(value))
+        return undefined;
+    try {
+        const url = new URL(value);
+        if (url.protocol === 'mailto:')
+            return value;
+        if ((url.protocol === 'http:' || url.protocol === 'https:') && url.hostname)
+            return value;
+    }
+    catch {
+        /* not an absolute address */
+    }
+    return undefined;
+}
+/** The parameters an attachment's picture address may carry, and nothing else. */
+const IMAGE_PARAMS = new Set(['table', 'key', 'inline', 'variant']);
+/**
+ * A picture's address, when it is one of this App's own attachments: the file
+ * route's inline mode for one row of a file resource,
+ * `/api/file?table=<resource>&key=<the row's key as JSON>&inline=1`. Relative
+ * to the App, so a mount point or a proxy's base path is the page's to add
+ * (`served`). `tables` narrows it to the App's file resources where the
+ * caller knows them (the server does). Anything else is no picture.
+ */
+export function richTextImage(raw, tables) {
+    const value = raw.trim();
+    if (!value.startsWith('/api/file?') || value.length > 1024)
+        return undefined;
+    const params = new URLSearchParams(value.slice('/api/file?'.length));
+    const names = [...params.keys()];
+    if (names.some((name) => !IMAGE_PARAMS.has(name)) || new Set(names).size !== names.length)
+        return undefined;
+    const table = params.get('table');
+    if (!table || !/^[A-Za-z_][A-Za-z0-9_.]{0,127}$/.test(table) || (tables && !tables.has(table)))
+        return undefined;
+    if (params.get('inline') !== '1')
+        return undefined;
+    const variant = params.get('variant');
+    if (variant !== null && variant !== 'thumb')
+        return undefined;
+    let key;
+    try {
+        key = JSON.parse(params.get('key') ?? '');
+    }
+    catch {
+        return undefined;
+    }
+    if (!key ||
+        typeof key !== 'object' ||
+        Array.isArray(key) ||
+        !Object.keys(key).length ||
+        Object.keys(key).length > 4 ||
+        Object.entries(key).some(([column, item]) => !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(column) ||
+            !((typeof item === 'string' && item.length <= 256) || (typeof item === 'number' && Number.isFinite(item)))))
+        return undefined;
+    return { table, key: key };
+}
+/** The address a picture of one attachment row is stored as: the same form `richTextImage` reads. */
+export function richTextImageAddress(table, key) {
+    return `/api/file?${new URLSearchParams({ table, key: JSON.stringify(key), inline: '1' })}`;
+}
+/**
+ * Whether an attribute's value is kept on an element: a link's address, a
+ * picture's, a task item's state, a list's kind, a mention's handle and
+ * whether it names a group, a code block's language, a cell's span. Undefined drops it. The caller has already
+ * checked the attribute is one the element keeps.
+ */
+export function richTextAttribute(element, name, value, images) {
+    if (name === 'href')
+        return richTextHref(value);
+    if (name === 'src')
+        return richTextImage(value, images) ? value.trim() : undefined;
+    if (name === 'alt')
+        return value.slice(0, 300);
+    if (name === 'data-type') {
+        if (element === 'ul')
+            return value === 'taskList' ? value : undefined;
+        if (element === 'li')
+            return value === 'taskItem' ? value : undefined;
+        if (element === 'span')
+            return value === 'mention' ? value : undefined;
+        return undefined;
+    }
+    if (name === 'data-checked')
+        return value === 'true' || value === 'false' ? value : undefined;
+    if (name === 'data-kind')
+        return element === 'span' && value === 'group' ? value : undefined;
+    if (name === 'data-id')
+        return MENTION_HANDLE.test(value) ? value : undefined;
+    if (name === 'class')
+        return element === 'code' && /^language-[A-Za-z0-9_+-]{1,32}$/.test(value) ? value : undefined;
+    if (name === 'start' || name === 'colspan' || name === 'rowspan')
+        return /^[1-9][0-9]{0,2}$/.test(value) ? value : undefined;
+    return undefined;
+}
+/** Elements that end a line of the plain text: blocks, list items, a table's cells and rows. */
+const BLOCK = /^(?:p|h[1-6]|li|blockquote|pre|tr|div|ul|ol|table|thead|tbody)$/i;
+const ENTITIES = Object.freeze({
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' ',
+});
+function decode(text) {
+    return text.replace(/&(#x[0-9a-f]{1,6}|#[0-9]{1,7}|[a-z]{2,8});/gi, (whole, name) => {
+        if (name[0] === '#') {
+            const code = name[1] === 'x' || name[1] === 'X' ? parseInt(name.slice(2), 16) : parseInt(name.slice(1), 10);
+            return Number.isFinite(code) && code > 0 && code <= 0x10ffff && !(code >= 0xd800 && code <= 0xdfff) ? String.fromCodePoint(code) : '';
+        }
+        return ENTITIES[name.toLowerCase()] ?? whole;
+    });
+}
+/* Text that ends in a list item's dash or box: the item's first paragraph goes on that line. */
+const ITEM_MARK = /\n(?:- |\[[ x]\] )[^\S\n]*$/;
+/**
+ * A rich text value's words: tags out, entities read, one line per block, a
+ * list item after a dash, a task with its box, a picture as its description.
+ * Pure text, never markup, whatever the value held — it is drawn as text.
+ */
+export function richTextPlain(html) {
+    if (typeof html !== 'string' || !html)
+        return '';
+    let text = '';
+    const tag = /<(\/?)([A-Za-z][A-Za-z0-9]*)\b((?:[^>"']|"[^"]*"|'[^']*')*)>|<!--[\s\S]*?-->/g;
+    let at = 0;
+    const dropped = new Set(RICH_TEXT_DROPPED);
+    let skipping;
+    /* Outside a code block a line break in the source is a space, as a browser draws it. */
+    let pre = 0;
+    const words = (part) => (pre ? part : part.replace(/\s+/g, ' '));
+    for (const match of html.matchAll(tag)) {
+        if (!skipping)
+            text += words(html.slice(at, match.index));
+        at = match.index + match[0].length;
+        const [, closing, rawName, attributes = ''] = match;
+        if (!rawName)
+            continue;
+        const name = rawName.toLowerCase();
+        if (skipping) {
+            if (closing && name === skipping)
+                skipping = undefined;
+            continue;
+        }
+        if (!closing && dropped.has(name)) {
+            if (!/\/\s*$/.test(attributes))
+                skipping = name;
+            continue;
+        }
+        if (name === 'pre')
+            pre = Math.max(0, pre + (closing ? -1 : 1));
+        if (name === 'br')
+            text += '\n';
+        else if (!closing && name === 'li') {
+            const checked = /\bdata-checked\s*=\s*["']?(true|false)/i.exec(attributes)?.[1];
+            text += `\n${checked === 'true' ? '[x] ' : checked === 'false' ? '[ ] ' : '- '}`;
+        }
+        else if (!closing && name === 'img') {
+            const alt = /\balt\s*=\s*"([^"]*)"|\balt\s*=\s*'([^']*)'/i.exec(attributes);
+            const said = (alt?.[1] ?? alt?.[2] ?? '').trim();
+            if (said)
+                text += ` ${said} `;
+        }
+        else if ((name === 'td' || name === 'th') && closing)
+            text += '\t';
+        else if (BLOCK.test(name) && (closing || !ITEM_MARK.test(text)))
+            text += '\n';
+    }
+    if (!skipping)
+        text += words(html.slice(at));
+    return decode(text)
+        .replace(/[^\S\n\t]+/g, ' ')
+        .split('\n')
+        .map((line) => line
+        .replace(/[\t ]+$/, '')
+        .replace(/^[\t ]+/, '')
+        .replace(/\s*\t\s*/g, ' · '))
+        .filter(Boolean)
+        .join('\n');
+}
+/** A value's words in one line, cut at a word near `most` characters with an ellipsis: a cell, a card, an excerpt. */
+export function richTextExcerpt(html, most = RICH_TEXT_EXCERPT) {
+    const line = richTextPlain(html).replace(/\s*\n\s*/g, ' · ');
+    if (line.length <= most)
+        return line;
+    const cut = line.slice(0, most);
+    const space = cut.lastIndexOf(' ');
+    return `${(space > most * 0.6 ? cut.slice(0, space) : cut).replace(/[\s·.,;:]+$/, '')}…`;
+}
+/** How many people and groups one value may @-mention: past it, it is a broadcast. */
+const MOST_MENTIONED = 20;
+/**
+ * Who a value @-mentions, as the editor stores them: a person as
+ * `<span data-type="mention" data-id="ada">`, a group (a team) with
+ * `data-kind="group"` beside it. Each once, in order, at most twenty in all.
+ * A mention is its stored handle, never the words drawn in it: the text
+ * `@Ada` inside the span is how it reads, and nobody is found by it.
+ */
+export function richTextMentioned(html) {
+    const people = new Set(), groups = new Set();
+    if (typeof html !== 'string')
+        return { people: [], groups: [] };
+    for (const match of html.matchAll(/<span\b[^>]*\bdata-type\s*=\s*"mention"[^>]*>/gi)) {
+        if (people.size + groups.size >= MOST_MENTIONED)
+            break;
+        const id = /\bdata-id\s*=\s*"([^"]*)"/i.exec(match[0])?.[1];
+        if (!id || !MENTION_HANDLE.test(id))
+            continue;
+        (/\bdata-kind\s*=\s*"group"/i.test(match[0]) ? groups : people).add(id);
+    }
+    return { people: [...people], groups: [...groups] };
+}
+/** The people's handles a value @-mentions (`<span data-type="mention" data-id="ada">`), each once, in order; a group's are `richTextMentioned`'s. */
+export function richTextMentions(html) {
+    return richTextMentioned(html).people;
+}

package/dist/shared/rollups.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Rollups: one number about the rows that point at a record — an order's
+ * line total, an account's open deals — declared once on the resource
+ * (`rollups: { line_total: sum('order_line', 'amount') }`) and read wherever
+ * a column of the record is: a list's `show`, a sort, a tab's condition, a
+ * record page's fields, a card's figure and facts, a queue's facts, a
+ * picker's query, a dashboard's measure and a breakdown's key — and through
+ * a reference, as `sales_order_id.lines`, wherever a path is.
+ *
+ * A rollup is never a column of the table. It is not in `TableMeta.columns`,
+ * so every path that reads one table by its own columns — an insert form, a
+ * plain `/api/query`, an export of the table, a filter box built from the
+ * schema — never sees it and never sends it to a single-table read, which
+ * would be a statement naming a column the database does not have. It lives
+ * beside the columns (`TableMeta.rollups`), where the path resolver finds it
+ * by name, and it is compiled only by the view compiler, as a correlated
+ * scalar subquery through one reference: the same construction as a view's
+ * aggregates (viewPaths.ts says why a subquery rather than a grouped join),
+ * so a list still has one row per record however many rollups it shows.
+ *
+ * The child rows are read through the statement's own relations
+ * (rowScope.ts), so a row policy or a tenant scope on the child narrows the
+ * number exactly as it narrows a related list of the same rows, and a reader
+ * whose catalog cannot see the child table, its column or the reference is
+ * served no rollup at all (appRollupRules), rather than a number built from
+ * rows they may not read.
+ */
+import type { Filter } from './filter.js';
+import type { ComputedColumn } from './computed.js';
+import type { ColumnMeta } from './schema.js';
+export declare const ROLLUP_FNS: readonly ['count', 'sum', 'min', 'max', 'latest'];
+export type RollupFn = (typeof ROLLUP_FNS)[number];
+/** A rollup as the catalog serves it and a view carries it: no request ever supplies one. */
+export interface Rollup {
+    fn: RollupFn;
+    /**
+     * The reference from the child rows to the record, as `child.column`
+     * (`+`-joined for a composite key): endpoints rather than a constraint
+     * name, so a layer that renames tables (an App's logical names, a
+     * source's prefix) can rewrite it without resolving anything.
+     */
+    via: string;
+    /** The child's column; absent for a count. */
+    column?: string;
+    /**
+     * A `latest`'s order: the child's column whose greatest value is the latest row (its key breaks a tie), and
+     * whose `column` the rollup reads — a payment's status, the last visit's outcome. A word about the rows, not a
+     * figure, so it is never summed. Through two references it is the inner level's: the outer reads the newest of
+     * all the rows joined to their middle record, not the newest of each middle's newest (viewLabels.ts).
+     */
+    by?: string;
+    /**
+     * A `latest` that reads a reference column (the newest lease's `resident_id`): the record it points at, so the value
+     * is drawn as that record's name and link and never as its key (referenceModel.ts).
+     */
+    references?: {
+        table: string;
+        column: string;
+    };
+    /**
+     * Set only on a rollup a path reads *through* (`resident.name`, viewPaths.ts): the value wanted is this column of the
+     * record the rollup's key names, read through that table's own relation, so a row policy narrows it as it narrows a
+     * join to the same record. The reader must be able to read both (rollupReads).
+     */
+    through?: {
+        table: string;
+        key: string;
+        column: string;
+    };
+    /** A `latest`'s vocabulary: the child column's own, so the word it reads is drawn, filtered and typed as that column is. */
+    allowed?: string[];
+    /**
+     * Set when `column` names a computed column of the child (computed.ts)
+     * rather than a stored one: its expression, constants folded, written
+     * inline over the child's row inside the aggregate — the same SQL a list
+     * of the child writes for it. It reads the child's own columns only, never
+     * a rollup or a reference (appRollupRules refuses those), so a rollup over
+     * it is still one subquery, and no rollup can come to read itself.
+     */
+    expression?: Pick<ComputedColumn, 'type' | 'expr' | 'reads'>;
+    /** Which child rows count — the rollup's `query`, over the child's own columns and paths through its references. */
+    filter?: Filter;
+    /**
+     * The computed columns of the child that `filter` names (`breached = true`), each its expression, constants
+     * and `now` folded: written over the row inside the narrowed relation, as `expression` is inside the aggregate.
+     * Each reads the child's own columns only (appRollupRules), so the figure is still one subquery.
+     */
+    computed?: Record<string, Pick<ComputedColumn, 'type' | 'expr' | 'reads'>>;
+    /**
+     * The tables a path in `filter` walks to, with the columns read there (`sales_order_id.status` reads
+     * `sales_order.id` and `sales_order.status`): what a reader must be able to read for the figure to be
+     * served (rollupReads), as the child's own columns are.
+     */
+    reach?: Array<{
+        table: string;
+        fields: string[];
+    }>;
+    /** The value's type: an integer for a count, the column's own otherwise. */
+    type: string;
+    /**
+     * Set when `column` names a rollup of the child rather than one of its
+     * columns — a customer's `lines: sum('sales_order', 'lines')`, the count
+     * of its orders' lines, which is how a rollup reaches two hops. The inner
+     * rollup is compiled inside the outer one's aggregate, each through its own
+     * child's relation, so a row policy narrows both levels. One level only:
+     * the inner one reads a column (appRollupRules says so when it does not).
+     *
+     * A rollup whose `whose` walks two references (`sum('time_entry', 'hours',
+     * { whose: 'task_id.project_id' })`) is served in the same shape: the outer
+     * reads the middle table (`task.project_id`) with no column of its own,
+     * the inner the rows and column declared, with the declared query. A count
+     * so built is the sum of the inner counts, and 0 where there are none; a
+     * max of maxes and a min of mins are the max and min of the rows; a latest
+     * is one ordered read over the rows joined to the middle table. The
+     * access layer holds a reader to both levels' tables and fields
+     * (rollupReads), as it does a rollup of a rollup.
+     */
+    of?: Rollup;
+}
+/**
+ * A rollup a view names, keyed by its path in `ViewDef.computed`: the rollup
+ * and the path prefix of the record it hangs off ('' for the view's base).
+ */
+export interface ComputedPath extends Rollup {
+    on: string;
+}
+/** A rollup read as a column: never written, null only where there are no rows to read (a count is 0). */
+export declare function rollupColumnMeta(name: string, rollup: Pick<Rollup, 'fn' | 'type' | 'allowed' | 'references'>): ColumnMeta;
+/** A view's or a breakdown's `computed` with every child table renamed. */
+export declare function renamedComputed<T extends {
+    computed?: Record<string, ComputedPath>;
+}>(def: T, rename: (table: string) => string): T;
+/**
+ * Every table a rollup reads rows of, with the fields it reads there: the
+ * reference it walks, the column it sums (not an inner rollup's name, which
+ * is no field, nor a computed column's, whose own reads stand for it) and
+ * the columns its query narrows by — the inner rollup's too. What an access
+ * layer holds a reader's grants against.
+ */
+export declare function rollupReads(rollup: Rollup): Array<{
+    table: string;
+    fields: string[];
+}>;

package/dist/shared/rollups.js

@@ -0,0 +1,64 @@
+export const ROLLUP_FNS = ['count', 'sum', 'min', 'max', 'latest'];
+/** A rollup read as a column: never written, null only where there are no rows to read (a count is 0). */
+export function rollupColumnMeta(name, rollup) {
+    return {
+        name,
+        type: rollup.type,
+        nullable: rollup.fn !== 'count',
+        primaryKey: false,
+        writable: false,
+        ...(rollup.allowed ? { allowed: rollup.allowed } : {}),
+        ...(rollup.references ? { references: rollup.references } : {}),
+    };
+}
+/** The child table a rollup's `via` names. */
+function rollupChild(via) {
+    return via.slice(0, via.lastIndexOf('.'));
+}
+/** `via` with its child table renamed — a layer mapping logical names to physical ones. */
+function renamedVia(via, rename) {
+    const dot = via.lastIndexOf('.');
+    return `${rename(via.slice(0, dot))}${via.slice(dot)}`;
+}
+/** A rollup with every child table it reads renamed, the inner one's too. */
+function renamedRollup(rollup, rename) {
+    return {
+        ...rollup,
+        via: renamedVia(rollup.via, rename),
+        ...(rollup.reach ? { reach: rollup.reach.map((read) => ({ ...read, table: rename(read.table) })) } : {}),
+        ...(rollup.references ? { references: { ...rollup.references, table: rename(rollup.references.table) } } : {}),
+        ...(rollup.through ? { through: { ...rollup.through, table: rename(rollup.through.table) } } : {}),
+        ...(rollup.of ? { of: renamedRollup(rollup.of, rename) } : {}),
+    };
+}
+/** A view's or a breakdown's `computed` with every child table renamed. */
+export function renamedComputed(def, rename) {
+    return def.computed
+        ? { ...def, computed: Object.fromEntries(Object.entries(def.computed).map(([path, rollup]) => [path, renamedRollup(rollup, rename)])) }
+        : def;
+}
+/**
+ * Every table a rollup reads rows of, with the fields it reads there: the
+ * reference it walks, the column it sums (not an inner rollup's name, which
+ * is no field, nor a computed column's, whose own reads stand for it) and
+ * the columns its query narrows by — the inner rollup's too. What an access
+ * layer holds a reader's grants against.
+ */
+export function rollupReads(rollup) {
+    const table = rollupChild(rollup.via);
+    const fields = [
+        ...rollup.via.slice(table.length + 1).split('+'),
+        ...(rollup.expression ? rollup.expression.reads : rollup.column && !rollup.of ? [rollup.column] : []),
+        ...(rollup.by === undefined ? [] : [rollup.by]),
+        // A path's first hop is the child's own reference column; the rest is in `reach`.
+        ...(rollup.filter?.groups ?? []).flatMap((group) => group.flatMap((c) => [c.column, ...(c.other === undefined ? [] : [c.other])].flatMap((name) => 
+        // A computed column's own reads stand for it, as `expression`'s do.
+        rollup.computed && Object.hasOwn(rollup.computed, name) ? rollup.computed[name].reads : name.split('.')[0].split('+')))),
+    ];
+    return [
+        { table, fields },
+        ...(rollup.reach ?? []),
+        ...(rollup.of ? rollupReads(rollup.of) : []),
+        ...(rollup.through ? [{ table: rollup.through.table, fields: [rollup.through.key, rollup.through.column] }] : []),
+    ];
+}

package/dist/shared/rowScope.d.ts

@@ -0,0 +1,72 @@
+import { type Filter, type SqlFragment, type SqlStyle } from './filter.js';
+import { type DatabaseSchema } from './schema.js';
+/** Internal, server-owned compiler input; never a member of a request definition.
+ * Exact catalog IDs only. With a scope present, missing resources deny rows.
+ * `true` explicitly allows all rows; filters address local columns, not paths.
+ * This primitive alone does not enable App authorization or tenant isolation.
+ */
+export interface RowScopeFilter extends Filter {
+    /** Private SQLite comparison metadata, never SQL or a request filter field.
+     * Applies BINARY collation to these local columns; LIKE keeps its own semantics. */
+    readonly binary?: readonly string[];
+}
+export type RowScope = Readonly<Record<string, boolean | RowScopeFilter>>;
+/** Composition must budget expanded data against the same capture limits. */
+export declare const ROW_SCOPE_LIMITS: Readonly<{
+    resources: 256;
+    conditions: 2048;
+    array: 4096;
+    nodes: 16384;
+    string: 16384;
+    characters: 262144;
+}>;
+/** Copy before validation so accessors, prototypes and later mutation cannot
+ * change what was checked. Bounds apply to the entire scope, not each table.
+ * Frozen nested values stay private; Readonly<Record> alone is not a snapshot.
+ */
+export declare function captureRowScope(input: RowScope): RowScope;
+/** A scope's text, where the text says all of it: undefined for anything JSON would say the same as something else
+ * (an undefined value, which it drops; a non-finite number; an object that is not a plain record). Only for data
+ * nothing can intercept — a copy this module or the tenant capture made — never a caller's live object, whose
+ * accessors JSON.stringify would run. */
+export declare function rowScopeText(value: unknown): string | undefined;
+/** Test-only: how many row scopes were copied and checked in full rather than handed back. */
+export declare const rowScopeCounters: {
+    checked: number;
+};
+/** Whether `value` is a row scope snapshotRowScope made: plain data, frozen all the way down, that nothing can change. */
+export declare function isRowScopeSnapshot(value: unknown): boolean;
+/** Capture can precede an async catalog load; catalog validation cannot. */
+export declare function snapshotRowScope(schema: DatabaseSchema, input: RowScope): RowScope;
+/** Every occurrence of a resource reads the same filtered relation, including
+ * LEFT JOIN targets and correlated aggregate children. CTE bindings precede
+ * outer filters, independent of SQL SELECT/FROM expression order. Call finish
+ * only after all relations have been discovered, then number outer bindings.
+ */
+export declare class ScopedRelations {
+    private schema;
+    private style;
+    private readonly scope;
+    private readonly names;
+    private readonly reserved;
+    private readonly definitions;
+    private readonly params;
+    private finished;
+    private ordinal;
+    constructor(schema: DatabaseSchema, style: SqlStyle, scope?: RowScope);
+    table: (id: string) => string;
+    private readonly narrowed;
+    /**
+     * A table's rows narrowed by an authored filter over its own columns — the
+     * rows a rollup counts (rollups.ts) — as one more definition here. A CTE
+     * rather than a WHERE inside the correlated subquery, for the parameters:
+     * a subquery can sit in the SELECT list, the WHERE and the ORDER BY at
+     * once, and `?` placeholders bind by position, so values written there
+     * would interleave with the outer filter's. Here they bind first, with the
+     * scope's, and the subquery names the relation with no values of its own.
+     * Read from the scoped relation where there is a scope, so the filter
+     * narrows within the reader's rows, never beside them.
+     */
+    filtered: (id: string, filter: Filter, written?: Readonly<Record<string, (own: (column: string) => string) => string>>) => string;
+    finish(): SqlFragment;
+}