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

package/dist/server/http/recordCompose.js

@@ -0,0 +1,167 @@
+import { findTable } from '../../shared/schema.js';
+import { validatePage } from '../../shared/page.js';
+import { RECORD_COMPOSE_PATH, recordPageReads, rowBody, whenBody, } from '../../shared/recordReads.js';
+import { canonicalText } from '../../shared/recordReadKeys.js';
+import { CapturedReply } from './captured.js';
+import { HttpError, send } from './reply.js';
+export const COMPOSE_PATH = RECORD_COMPOSE_PATH;
+/** How many related rows a reader may ask for a page: the sizes the list offers (client relatedRows.ts), and no more. */
+const MOST_ROWS = 50;
+/** Commands asked about at once, as the availability route takes them. */
+const MOST_CHECKS = 16;
+const failed = (answer) => !answer ||
+    answer.status >= 400 ||
+    Boolean(answer.body &&
+        typeof answer.body === 'object' &&
+        ('error' in answer.body ||
+            ('errors' in answer.body &&
+                Array.isArray(answer.body.errors) &&
+                answer.body.errors.length > 0)));
+export async function composeRecordPage({ ctx, source, body, post, hooks, }) {
+    const { res, identity } = ctx;
+    const key = body.key;
+    const rows = body.rows ?? 10;
+    const tab = body.tab;
+    if (!key ||
+        typeof key !== 'object' ||
+        Array.isArray(key) ||
+        typeof rows !== 'number' ||
+        !Number.isInteger(rows) ||
+        rows < 1 ||
+        rows > MOST_ROWS ||
+        (tab !== undefined && (typeof tab !== 'string' || tab.length > 512)) ||
+        (typeof body.page !== 'string' && (!body.page || typeof body.page !== 'object' || Array.isArray(body.page)))) {
+        throw new HttpError(400, 'A composed record page names a page, a record key and a page size.');
+    }
+    /* A part asked on the page's behalf: through the route its section's own
+       request reaches, answered into memory. What that route would refuse, or
+       throw, leaves the part out. */
+    const ask = async (path, given) => {
+        if (!hooks.mayAsk(ctx, path))
+            return undefined;
+        const reply = new CapturedReply();
+        try {
+            await post(reply.asResponse(), path, given);
+        }
+        catch {
+            return undefined;
+        }
+        return reply.answer();
+    };
+    const record = key;
+    const resources = hooks.resources(ctx, source);
+    const names = {
+        schema: source.schema,
+        app: ctx.appConfigured,
+        recordLabel: (table) => resources[table]?.recordLabel,
+        defined: (table) => resources[table]?.defined,
+    };
+    const options = { rows, history: true, ...(tab === undefined ? {} : { tab: tab }) };
+    /* What the page reads that its plan does not decide — the record's row,
+       its history, its verbs, each `when` — is asked beside the plan, from
+       the page as the plan will find it; the lists and figures the plan
+       builds are asked once it comes. Should the plan's page not be that
+       page after all, the early answers are dropped and asked again. */
+    const reading = (page, base, plans, started = []) => {
+        const answered = [];
+        const keep = (asked, answer) => {
+            if (!failed(answer))
+                answered.push({ ...asked, status: answer.status, reply: answer.body });
+        };
+        const { row, parts, reads } = recordPageReads(names, page, base, plans, record, options);
+        /* The record's fixed edits ask their `when` of the row, as a section does. */
+        const actions = resources[base.id]?.actions ?? [];
+        for (const when of new Set(actions.flatMap((action) => (!action.command && action.when ? [action.when] : [])))) {
+            reads.push({ path: '/api/run', body: whenBody(base, record, when) });
+        }
+        const whole = async () => {
+            const asked = { path: '/api/view/run', body: rowBody(page.id, base, record, row, 'row') };
+            const answer = await ask(asked.path, asked.body);
+            if (!failed(answer))
+                return keep(asked, answer);
+            /* One column this reader may not read refuses the whole row: each reader of it is asked alone, as it would ask. */
+            await Promise.all(parts.map(async ({ part, columns }) => {
+                const alone = { path: '/api/view/run', body: rowBody(page.id, base, record, columns, part) };
+                keep(alone, await ask(alone.path, alone.body));
+            }));
+        };
+        const commands = actions.flatMap((action) => (action.command && action.command.target === base.id ? [action.command] : []));
+        const checks = [...new Map(commands.map((command) => [command.id, command])).values()]
+            .slice(0, MOST_CHECKS)
+            .map((command) => ({ command: command.id, commandVersion: command.version, keys: [record] }));
+        const availability = async () => {
+            if (!checks.length || identity.id === undefined || !hooks.availability || !hooks.mayAsk(ctx, '/api/commands/availability'))
+                return;
+            const asked = { path: '/api/commands/availability', body: { checks } };
+            keep(asked, await hooks.availability(ctx, checks));
+        };
+        const begun = new Map(started.map(([asked, answer]) => [readKey(asked), answer]));
+        /* The page's own row first, its verbs last: they are advice, and wait behind what is shown. */
+        const done = Promise.all([
+            whole(),
+            ...reads.map(async (asked) => keep(asked, await (begun.get(readKey(asked)) ?? ask(asked.path, asked.body)))),
+            availability(),
+        ]);
+        return { reads: new Set(reads.map((asked) => readKey(asked))), done: done.then(() => answered) };
+    };
+    const expected = expectedPage(ctx, source, body.page, hooks);
+    const expectedBase = expected && findTable(source.schema, expected.base);
+    /* The history is asked first: it is the longest chain (its store is
+       attested, then read), and a reader pool is a queue. Then the plan, which
+       the lists wait on; then the rest. */
+    const history = expected && expectedBase
+        ? recordPageReads(names, expected, expectedBase, [], record, options)
+            .reads.filter((asked) => asked.path === '/api/record-history')
+            .map((asked) => [asked, ask(asked.path, asked.body)])
+        : [];
+    const planning = ask('/api/pages/plan', { page: body.page, key });
+    const early = expected && expectedBase ? reading(expected, expectedBase, [], history) : undefined;
+    const plan = await planning;
+    const planned = failed(plan) ? undefined : plan.body;
+    const base = planned && findTable(source.schema, planned.page.base);
+    /* No plan, no page: the client asks the plan itself, and is told why in
+       the plan's own words. What was asked beside it is dropped, once it has
+       settled: every read ends inside the request (and the row policy's
+       context) that asked it. */
+    if (!planned || !base) {
+        await Promise.allSettled([early?.done, ...history.map(([, answer]) => answer)]);
+        return send(res, 200, { planned: false });
+    }
+    const kept = early && canonicalText(expected) === canonicalText(planned.page) ? early : undefined;
+    if (early && !kept)
+        await early.done;
+    let answered;
+    if (kept) {
+        /* Only what the plan adds: its lists, figures, timelines and custom reads. */
+        const { reads } = recordPageReads(names, planned.page, base, planned.plans, record, options);
+        const later = reads.filter((asked) => !kept.reads.has(readKey(asked)));
+        const more = await Promise.all(later.map(async (asked) => ({ asked, answer: await ask(asked.path, asked.body) })));
+        answered = [
+            ...(await kept.done),
+            ...more.flatMap(({ asked, answer }) => (failed(answer) ? [] : [{ ...asked, status: answer.status, reply: answer.body }])),
+        ];
+    }
+    else
+        answered = await reading(planned.page, base, planned.plans).done;
+    send(res, 200, { planned: true, page: planned.page, plans: planned.plans, reads: answered });
+}
+const readKey = (asked) => `${asked.path}\u0000${canonicalText(asked.body)}`;
+/**
+ * The page the plan will find, found as `/api/pages/plan` finds it
+ * (authoringRoutes.ts): given whole, the table's suggested page, or the
+ * connection's configured page by name — validated against this schema.
+ * Only to ask the page's own reads beside the plan; the plan still decides,
+ * and an answer read for any other page is dropped.
+ */
+function expectedPage(ctx, source, asked, hooks) {
+    const name = ctx.registry.list().find((c) => c.id === source.connectionId)?.name;
+    const found = typeof asked === 'object' && asked !== null
+        ? asked
+        : String(asked ?? '').startsWith('suggested:')
+            ? hooks.suggested(source, String(asked).slice('suggested:'.length))
+            : ctx.configPages.find((page) => page.id === String(asked ?? '') && (!page.connection || page.connection === source.connectionId || page.connection === name));
+    if (!found || typeof found.base !== 'string' || !Array.isArray(found.sections))
+        return undefined;
+    const page = validatePage(source.schema, found);
+    return page.error ? undefined : page;
+}

package/dist/server/http/recordWrites.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The record writes both products serve: update, insert (a file's upload
+ * among them) and delete. Every one asks the product's write gate first
+ * (`gates.write`: the connection's `writable` flag, then the reader's
+ * grant), and every committed write goes through the one recorder that
+ * anchors it to the source it touched, then to the product's `after.write`.
+ *
+ * What an App adds is `RecordRules`: the words its refusals are said in, the
+ * label its history gives an edit, what it does not delete, a New form's
+ * file, tags and lines, and replies that say no more than an App reader is
+ * told. Without them a write is the database browser's: journaled for its
+ * Undo, and refused in the database's own words.
+ */
+import type { ServerResponse } from 'node:http';
+import { type InsertRequest, type InsertResult } from '../../adapters/adapter.js';
+import { type LineCollection } from '../recordWriteOperations.js';
+import { sendResource } from './reply.js';
+import type { PostContext } from './context.js';
+type Values = Record<string, string | number | boolean | null>;
+/** What a write that failed says, in its errors list: a message, and in an App its code and safe fields. */
+type WriteFailure = NonNullable<Parameters<typeof sendResource<'/api/insert'>>[3]['errors']>[number];
+/** A file placed before its row is written, discarded when the row is not (files/fileStorage.ts). */
+interface PlacedValues {
+    readonly values: Values;
+    discard(): Promise<void>;
+}
+/** What a New form sends beside its record, judged: the link rows its tags are, and its lines. */
+interface Alongside {
+    readonly alongside?: (result: InsertResult) => InsertRequest[];
+    readonly lines?: LineCollection[];
+}
+/** An answer a rule gave instead of going on. */
+interface Answered {
+    readonly status: number;
+    readonly error: string;
+}
+/**
+ * An App's rules for its record writes (mistri: http/appRecordWrites.ts).
+ * Absent, the database browser's: a write is journaled, the upload, tags and
+ * lines of a New form are refused as no App declares them, and a failure is
+ * said in the database's own words.
+ */
+export interface RecordRules {
+    /** What the record history calls an edit (recordHistory.ts updateActionLabel). */
+    label(post: PostContext, table: string, values: Values): string | undefined;
+    /** Whether the App deletes rows of `tableId` at all (appDeletable). */
+    deletes(post: PostContext, tableId: string): boolean;
+    /** An upload's columns, placed where its resource keeps its bytes. */
+    upload(post: PostContext, tableId: string | undefined): Promise<PlacedValues | Answered>;
+    /** A New form's tags and lines, judged against what the App declares. */
+    alongside(post: PostContext, tableId: string | undefined): Answered | Alongside;
+    /** The App's own rules refusing the record (its validation, a line's `consumes`): answered in the App's shape. True when answered. */
+    refused(res: ServerResponse, path: '/api/insert' | '/api/update', error: unknown): boolean;
+    /** A write that failed, said by code and never in a driver's words (appErrors.ts). */
+    failure(post: PostContext, error: unknown, completed: boolean): WriteFailure;
+    /** A delete's impact report, when a count fails. */
+    impact(error: unknown): string;
+    /** A reply cut to what an App reader is told (appResponses.ts). */
+    reply(body: Record<string, unknown>, kind: 'read' | 'write'): Record<string, unknown>;
+}
+/** What a product decides about the record writes. */
+export interface RecordHooks {
+    readonly gates: {
+        /** Why a write to `tableId` is refused, or null. An update may reach a table a role runs fixed actions on. */
+        write(post: PostContext, tableId: string | undefined, update?: boolean): string | null;
+    };
+    readonly after?: {
+        /** A committed write's record: its search document follows it, queued and never awaited. */
+        write(post: PostContext, table: string, key: Record<string, unknown>): void;
+    };
+    readonly rules?: RecordRules;
+}
+/**
+ * What every write on this request shares: the options the recorded
+ * operations take — the source's own adapter, and whether the write is
+ * journaled. The database browser journals every write, for its Undo; an App
+ * has no Undo and journals none (recordWriteOperations.ts `unrecorded`). The
+ * import route (importRoutes.ts) writes through the same.
+ */
+export declare function recordedWrites(post: Pick<PostContext, 'adapter' | 'connection' | 'who' | 'resources'>, journal: boolean): {
+    writeOptions: (table: string) => {
+        adapter: import("@mistriwork/engine/adapters/adapter.js").Adapter;
+        connection: string;
+        by: string | undefined;
+        journal: boolean;
+    };
+};
+export declare function recordWriteRoutes(post: PostContext, hooks: RecordHooks): Promise<boolean>;
+export {};

package/dist/server/http/recordWrites.js

@@ -0,0 +1,298 @@
+import { Refusal, TransactionOutcomeUnknown, WriteConflict } from '../../adapters/adapter.js';
+import { attributeAction } from '../../adapters/writeAttribution.js';
+import { isPoolBusy } from '../../adapters/poolMetrics.js';
+import { lockTimedOut } from '../../adapters/writeLanes.js';
+import { deletionDependents, recordedDelete, recordedInsert, recordedUpdate } from '../recordWriteOperations.js';
+import { AppAccessDenied } from '../columnGrants.js';
+import { deleteImpact } from '../impact.js';
+import { explainWriteFailure, writeFailureOutcome, writeRefusalStatus } from '../constraints.js';
+import { findTable } from '../../shared/schema.js';
+import { FILE_UPLOAD_PATH, bytesLabelled, send, sendBusy, sendResource, sendRowLocked } from './reply.js';
+/* A failed insert or update's status. The database refusing it for good — a key taken, a reference to nothing, a
+   value its column cannot hold — is 409 or 422 (constraints.ts writeRefusalStatus); it was a 200 whose body alone
+   said `rejected`, and a client that read the status took a refused write for a saved one (a live load test). One
+   that may have landed, or that nothing recognizes as refused, keeps the 200 and its `unknown` outcome. */
+const refusedStatus = (err, completed) => (completed ? 200 : (writeRefusalStatus(err) ?? 200));
+/**
+ * What every write on this request shares: the options the recorded
+ * operations take — the source's own adapter, and whether the write is
+ * journaled. The database browser journals every write, for its Undo; an App
+ * has no Undo and journals none (recordWriteOperations.ts `unrecorded`). The
+ * import route (importRoutes.ts) writes through the same.
+ */
+export function recordedWrites(post, journal) {
+    const { adapter, connection, who, resources } = post;
+    // resources has already been authorized. Anchor the write to the exact
+    // source without reopening an unguarded registry adapter or using its default.
+    const writeOptions = (table) => {
+        const owner = resources?.connectionFor(table) ?? connection;
+        return { adapter: resources?.forConnection(owner) ?? adapter, connection: owner, by: who, journal };
+    };
+    return { writeOptions };
+}
+export async function recordWriteRoutes(post, hooks) {
+    const { res, path, body, adapter, schema, registry, access, wholeRowWrites } = post;
+    const rules = hooks.rules;
+    const { writeOptions } = recordedWrites(post, !rules);
+    const indexed = (table, key) => hooks.after?.write(post, table, key);
+    /* A record's lines are records of their own, and what follows a write follows them too. */
+    const linesIndexed = (lines) => {
+        for (const line of lines ?? [])
+            for (const key of line.written ?? [])
+                indexed(line.table, key);
+    };
+    /* A file's object and hash are written for the reader and never shown to it (appAccess.ts withFileColumns). */
+    const internal = access?.internal?.get(String(body.table ?? ''));
+    const shown = (record) => internal && record && typeof record === 'object' && !Array.isArray(record)
+        ? Object.fromEntries(Object.entries(record).filter(([column]) => !internal.has(column)))
+        : record;
+    const sendData = (value) => {
+        const reply = { ...value };
+        for (const field of ['applied', 'row', 'before'])
+            if (field in reply)
+                reply[field] = bytesLabelled(shown(reply[field]));
+        send(res, 200, rules ? rules.reply(reply, 'write') : reply);
+    };
+    const failureOf = async (err, completed, values) => rules
+        ? rules.failure(post, err, completed)
+        : { message: await explainWriteFailure(adapter, schema, String(body.table ?? ''), values, err.message) };
+    /**
+     * Update one record through the shared transaction and history service.
+     *
+     * Note what is *not* checked here: whether the client thinks it is in write
+     * mode. That toggle is a UI affordance, and a guard that lives in the
+     * browser is not a guard. The adapter independently verifies the key is the
+     * whole primary key, counts the matching rows, and refuses anything other
+     * than exactly one.
+     */
+    if (path === '/api/update') {
+        /* The gate the server can actually enforce.
+    
+           Write mode in the browser is a deliberate act before typing, and it is
+           not a permission — the client decides whether to *offer* editing, and a
+           guard in the browser is not a guard. Until a connection says it is
+           writable, anything that could reach this endpoint could write to it —
+           and an app may narrow that to the tables it names. */
+        const refused = hooks.gates.write(post, findTable(schema, String(body.table ?? ''))?.id, true);
+        if (refused) {
+            send(res, 403, { error: refused, code: 'forbidden' });
+            return true;
+        }
+        if (!adapter.update) {
+            send(res, 501, { error: `${schema.dialect} connections are read-only in this build.` });
+            return true;
+        }
+        /* `values` is the real shape; `column`/`value` is accepted as the
+           one-field form so a single edit does not have to build an object. */
+        const values = (body.values ?? (body.column ? { [String(body.column)]: body.value ?? null } : {}));
+        let completed = false;
+        try {
+            const table = String(body.table ?? '');
+            const key = (body.key ?? {});
+            const expected = body.expected;
+            const { result, undoId } = await attributeAction(rules?.label(post, table, values), () => recordedUpdate(writeOptions(table), { table, key, values, ...(expected === undefined ? {} : { expected }) }));
+            completed = true;
+            indexed(table, key);
+            sendData({ ...result, ...(undoId === undefined ? {} : { undoId }) });
+            return true;
+        }
+        catch (err) {
+            if (!completed && lockTimedOut(err)) {
+                sendRowLocked(res);
+                return true;
+            }
+            if (!completed && isPoolBusy(err)) {
+                sendBusy(res, {}, true, err);
+                return true;
+            }
+            if (!completed && rules?.refused(res, path, err))
+                return true;
+            if (!completed && (err instanceof Refusal || err instanceof WriteConflict))
+                throw err;
+            /* Pointing an existing row at a row that is not there is the same
+               mistake as inserting one, and gets the same answer. */
+            const failure = await failureOf(err, completed, values);
+            sendResource(res, path, refusedStatus(err, completed), {
+                errors: [failure],
+                outcome: completed ? 'unknown' : writeFailureOutcome(err),
+            });
+            return true;
+        }
+    }
+    /**
+     * Add a row. The same gate as /api/update, because it is the same act one
+     * tense earlier. Refusals — a column that does not exist, null into NOT
+     * NULL — are 400s the adapter words; a constraint the *database* enforces
+     * comes back with its own message in the `rejected` envelope, because a
+     * UNIQUE violation is the user's to fix and the engine names the constraint
+     * better than a paraphrase would — at 409 or 422 (refusedStatus), never a
+     * 2xx a client reading only the status would take for a save. The outcome
+     * distinguishes recognized constraint rejections from unconfirmed failures
+     * that must not invite a blind retry.
+     */
+    if (path === '/api/insert' || path === FILE_UPLOAD_PATH) {
+        const tableId = findTable(schema, String(body.table ?? ''))?.id;
+        const refused = hooks.gates.write(post, tableId);
+        if (refused) {
+            send(res, 403, { error: refused, code: 'forbidden' });
+            return true;
+        }
+        if (!adapter.insert) {
+            send(res, 501, { error: `${schema.dialect} connections are read-only in this build.` });
+            return true;
+        }
+        let values;
+        let placed;
+        if (path === FILE_UPLOAD_PATH) {
+            /* A file is a row like any other: one insert on this path, with the
+               grants, validation and history an insert gets, and the upload's bytes,
+               name, type and size in the columns the resource's `file` names. */
+            const upload = rules ? await rules.upload(post, tableId) : { status: 404, error: 'This resource does not hold files.' };
+            if ('error' in upload) {
+                send(res, upload.status, { error: upload.error });
+                return true;
+            }
+            placed = upload;
+            values = placed.values;
+        }
+        else {
+            if (!body.values || typeof body.values !== 'object' || Array.isArray(body.values)) {
+                send(res, 400, { error: 'Insert values must be an object. Use {} explicitly to insert database defaults.' });
+                return true;
+            }
+            values = body.values;
+        }
+        /* A record's tags and its lines, sent with it from a New form: each written
+           in the record's transaction, so the record never stands without them. */
+        let alongside = {};
+        if (path === '/api/insert' && (body.tags !== undefined || body.lines !== undefined)) {
+            const judged = rules
+                ? rules.alongside(post, tableId)
+                : body.tags !== undefined
+                    ? { status: 400, error: 'This resource carries no tags.' }
+                    : { status: 400, error: 'Lines are saved with a record of an App that declares them.' };
+            if ('error' in judged) {
+                send(res, judged.status, { error: judged.error });
+                return true;
+            }
+            alongside = judged;
+        }
+        let completed = false;
+        try {
+            const table = String(body.table ?? '');
+            const { result, undoId } = await recordedInsert(writeOptions(table), { table, values }, alongside.alongside, alongside.lines);
+            completed = true;
+            indexed(table, result.key);
+            linesIndexed(alongside.lines);
+            sendData({ ...result, ...(undoId === undefined ? {} : { undoId }) });
+            return true;
+        }
+        catch (err) {
+            // A row that was not written leaves no object behind; one that may have been keeps it for the sweep to judge.
+            if (placed && !completed && !(err instanceof TransactionOutcomeUnknown))
+                await placed.discard();
+            if (!completed && lockTimedOut(err)) {
+                sendRowLocked(res);
+                return true;
+            }
+            if (!completed && isPoolBusy(err)) {
+                sendBusy(res, {}, true, err);
+                return true;
+            }
+            if (!completed && rules?.refused(res, '/api/insert', err))
+                return true;
+            if (!completed && err instanceof Refusal)
+                throw err;
+            /* "FOREIGN KEY constraint failed" names nothing on SQLite. The graph
+               is right here, and one lookup on the failure path turns it into the
+               column, the value and the row that is missing. */
+            const failure = await failureOf(err, completed, values);
+            sendResource(res, '/api/insert', refusedStatus(err, completed), {
+                errors: [failure],
+                outcome: completed ? 'unknown' : writeFailureOutcome(err),
+            });
+            return true;
+        }
+    }
+    /**
+     * Remove a row, having first said what removing it would do.
+     *
+     * This is the endpoint tablewalk can do better than most clients, and the
+     * reason is structural rather than clever: it already counts what points at a
+     * row, so it can answer "what breaks" *before* the delete rather than
+     * reporting a constraint violation afterwards.
+     *
+     * The count alone is not the answer. Three rows pointing at this one means
+     * three rows deleted under `cascade`, three rows left with a hole under `set
+     * null`, and a refused delete under `restrict` — three different outcomes
+     * behind one number. So the impact report carries the rule beside the count,
+     * and a rule the adapter could not determine is reported as unknown rather
+     * than assumed harmless.
+     *
+     * Two calls, deliberately. Without `confirm` this only reports; with it, it
+     * deletes. A destructive endpoint that also happens to be the way you ask
+     * about the damage is one typo away from doing it.
+     */
+    if (path === '/api/delete') {
+        if (!adapter.remove) {
+            send(res, 501, { error: `${schema.dialect} connections cannot delete in this build.` });
+            return true;
+        }
+        const refused = hooks.gates.write(post, findTable(schema, String(body.table ?? ''))?.id);
+        if (refused) {
+            send(res, 403, { error: refused, code: 'forbidden' });
+            return true;
+        }
+        if (rules && !rules.deletes(post, findTable(schema, String(body.table ?? ''))?.id ?? '')) {
+            send(res, 403, { error: 'This app does not delete these records.' });
+            return true;
+        }
+        const tableId = String(body.table ?? '');
+        const key = (body.key ?? {});
+        const table = findTable(schema, tableId);
+        if (!table) {
+            send(res, 404, { error: `Unknown table "${tableId}"` });
+            return true;
+        }
+        if (wholeRowWrites && !wholeRowWrites.has(tableId))
+            throw new AppAccessDenied();
+        const impact = await deleteImpact(adapter, schema, tableId, key, rules ? (error) => rules.impact(error) : undefined);
+        if (body.confirm !== true) {
+            sendResource(res, path, 200, { impact, deleted: false });
+            return true;
+        }
+        /* `restrict` and `no action` are left to the database rather than refused
+           here. The engine enforces them and its message names the constraint;
+           a second implementation of the same rule is how the two come to
+           disagree, and tablewalk would be the one that was wrong. */
+        let completed = false;
+        try {
+            const options = writeOptions(tableId);
+            /* What the deletion may change, for the journal's Undo, is read off
+               the database's own catalog. An App journals nothing. */
+            const dependents = options.journal
+                ? deletionDependents((await registry.open(options.connection)).schema, tableId, (table) => table)
+                : undefined;
+            const { result, undoId } = await recordedDelete(options, { table: tableId, key }, dependents);
+            completed = true;
+            indexed(tableId, key);
+            sendData({ impact, deleted: true, ...result, ...(undoId === undefined ? {} : { undoId }) });
+            return true;
+        }
+        catch (err) {
+            if (!completed && lockTimedOut(err)) {
+                sendRowLocked(res, { impact, deleted: false });
+                return true;
+            }
+            if (!completed && isPoolBusy(err)) {
+                sendBusy(res, { impact, deleted: false }, true, err);
+                return true;
+            }
+            const outcome = completed ? 'unknown' : err instanceof Refusal ? 'rejected' : writeFailureOutcome(err);
+            const errors = [rules ? rules.failure(post, err, completed) : { message: err.message }];
+            sendResource(res, path, outcome === 'unknown' ? 200 : (writeRefusalStatus(err) ?? 400), outcome === 'unknown' ? { impact, deleted: null, outcome, errors } : { impact, deleted: false, outcome, errors });
+            return true;
+        }
+    }
+    return false;
+}

package/dist/server/http/refusalReport.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Every refusal names its cause — to the people allowed to hear it.
+ *
+ * A caller is told one fixed sentence, and must be: a driver's error names
+ * columns and values, a clash on a hidden unique column says that a row
+ * exists, and a signed-out visitor is owed nothing about how an App is built.
+ * But a bare 503 with nothing logged anywhere cost Keystone's authors hours
+ * each time — a scoped command whose parent was outside its footprint, an
+ * audit entry past its bound, `me` in a rollup. So the reason is recorded on
+ * the refusal where it is decided (`recordRefusalCause`, shared/refusal.ts),
+ * and said here, at the one place a request's failure becomes its answer:
+ *
+ * - on the operator's stderr, always, for a server failure (5xx) or a refusal
+ *   that recorded why — the terminal an author runs the server in;
+ * - in the answer itself, as `cause`, only when the reader is the App's
+ *   author at work (`noteAuthorRequest`): signed in as its administrator (the
+ *   `admin` role, the account that may already act as anyone), over a
+ *   loopback listener nothing else can reach, at an App the server is
+ *   watching in its source directory — the edit loop, where a save reloads.
+ *   Never a signed-out visitor or an ordinary account, never a build, never a
+ *   listener the network reaches or a proxy speaks for.
+ */
+import type { IncomingMessage } from 'node:http';
+import { type Bound } from './trust.js';
+/** This App is served from its source and reloads on save. */
+export declare function authoringApp(path: string): void;
+/** Mark this request as the author's own, when it is: see the module comment. */
+export declare function noteAuthorRequest(req: IncomingMessage, bound: Bound, administrator: boolean, apps: ReadonlyArray<{
+    path: string;
+    build?: unknown;
+}>): void;
+/**
+ * Say a refused request to the operator, and return the sentence its author
+ * may read, if this request is the author's. Quiet for an ordinary refusal
+ * that recorded nothing — a 404 for a typo is not the operator's business —
+ * unless `always`: an error that was not a refusal at all, answered as one.
+ */
+export declare function reportRefusal(req: IncomingMessage, status: number, code: string | undefined, heard: string | undefined, error: unknown, always?: boolean): string | undefined;

package/dist/server/http/refusalReport.js

@@ -0,0 +1,63 @@
+import { refusalReasons, refusalSaid } from '../../shared/refusal.js';
+import { clientTrusted } from './trust.js';
+import { AppAccessDenied } from '../columnGrants.js';
+import { TenantContextError } from '../evidence.js';
+import { currentSpan, log } from '../../adapters/telemetry/trace.js';
+import { product } from '../product.js';
+/* A denial's own sentence says nothing its caller was not told: an ordinary
+   refusal of an ordinary request, not a reason. */
+const OPAQUE = new Set([new AppAccessDenied().message, new TenantContextError().message]);
+const authors = new WeakSet();
+/* The Apps this process is authoring: served from source and watched, so a
+   save reloads them (cli/serve.ts). By path, since a reload replaces the
+   loaded App and a request works on a copy of it. */
+const authoring = new Set();
+/** This App is served from its source and reloads on save. */
+export function authoringApp(path) {
+    authoring.add(path);
+}
+/** Mark this request as the author's own, when it is: see the module comment. */
+export function noteAuthorRequest(req, bound, administrator, apps) {
+    if (administrator &&
+        apps.length &&
+        apps.every((app) => !app.build && authoring.has(app.path)) &&
+        clientTrusted(bound) &&
+        !bound.identityHeader &&
+        !bound.trustedProxies?.length)
+        authors.add(req);
+}
+/** What the operator is told: the error's own words when it is no refusal at
+    all (a driver's, a bug), then each reason recorded beneath it. */
+function reasonsFor(error, heard) {
+    const own = error instanceof Error && error.message && error.message !== heard ? [error.message] : [];
+    return [...new Set([...own, ...recorded(error)])].filter((reason) => reason !== heard && !OPAQUE.has(reason));
+}
+const recorded = (error) => refusalReasons(error).filter((reason) => !OPAQUE.has(reason));
+/**
+ * Say a refused request to the operator, and return the sentence its author
+ * may read, if this request is the author's. Quiet for an ordinary refusal
+ * that recorded nothing — a 404 for a typo is not the operator's business —
+ * unless `always`: an error that was not a refusal at all, answered as one.
+ */
+export function reportRefusal(req, status, code, heard, error, always = false) {
+    const reasons = reasonsFor(error, heard);
+    /* The same reasons, on the request's span: the code and status travel, the
+       reasons stay local for the dev observer, where "Open in observer" leads. */
+    const span = currentSpan();
+    span?.setAttributes({ 'mistri.refusal.code': code ?? String(status), 'mistri.refusal.status': status });
+    span?.detail(() => ({ refusal: { status, ...(code ? { code } : {}), ...(heard ? { said: heard } : {}) }, because: reasons }));
+    log(status >= 500 ? 'error' : 'warn', 'refusal', `Request refused (${status}${code ? ` ${code}` : ''})`, {
+        attributes: { 'mistri.refusal.code': code, 'http.response.status_code': status },
+        detail: () => ({ said: heard, because: reasons }),
+    });
+    /* A refusal that said its rule (sayRefusal) is the operator's business too: a role or a policy that refuses
+       what its author meant it to allow is found here, not first with diagnostics on (field report TR7). */
+    if (status < 500 && !recorded(error).length && !refusalSaid(error) && !always)
+        return undefined;
+    const path = (req.url ?? '').split('?')[0];
+    console.error(`${product()}: ${req.method ?? 'GET'} ${path} refused (${status}${code ? ` ${code}` : ''})${heard ? `: ${heard}` : ''}`);
+    for (const reason of reasons)
+        console.error(`  because: ${reason}`);
+    // The innermost reason is the one that names the rule, the table or the column.
+    return authors.has(req) ? reasons.at(-1) : undefined;
+}