@substrat-run/contracts 0.142.0 → 0.144.0

package/dist/operations.js

@@ -26,7 +26,9 @@
  */
 import { LIST_PAGE_MAX } from './pagination.js';
 import { z } from 'zod';
-import { primaryKeyOf } from './model.js';
+import { entityStateName, entityStateOutput } from './entity-state.js';
+import { DERIVED_KINDS, primaryKeyOf, stampsOf, } from './model.js';
+import { acceptsNull, baseDefOf } from './zod-read.js';
 // ---------------------------------------------------------------------------
 // The composer.
 // ---------------------------------------------------------------------------
@@ -61,6 +63,7 @@ export function defineOperations(entities, _permissions, engines) {
         assertFieldBagsDeclareConcurrency(operations, entities, engines ?? []);
         assertPatchInputs(operations);
         assertTrashedDeclarations(operations, entities);
+        assertHandlersDeclared(operations, entities);
         return operations;
     };
 }
@@ -475,10 +478,640 @@ function assertPatchInputs(operations) {
         }
     }
 }
+/**
+ * Every derived declaration's plan, keyed by the declaration object itself. Keyed per operation
+ * rather than per map so a module that spreads its operations into a larger map still reaches
+ * them, and module-private so nothing but `defineOperations` can say what a handler does.
+ */
+const DERIVATION_PLANS = new WeakMap();
+/**
+ * The plan `defineOperations` recorded for a `derive` declaration — `undefined` for anything else,
+ * including a declaration that never passed through `defineOperations`.
+ */
+export function derivationPlanOf(operation) {
+    return DERIVATION_PLANS.get(operation);
+}
+/** The column kinds a derived write binds as they arrive: a JSON or boolean column needs encoding. */
+const DERIVED_WRITE_KINDS = new Set(['string', 'number', 'literal']);
+/** This module's entity whose `fields` the output IS, by identity — a projection is not the row. */
+function entityOfOutput(output, entities) {
+    return Object.keys(entities).find((name) => entities[name]?.fields === output);
+}
+/** The entity's definition and the plan's shared head, or the clause the entity fails. */
+function derivableEntity(entityName, entities) {
+    const def = entities[entityName];
+    if (!def)
+        return `'${entityName}' is not this module's entity — a composed engine's table is the engine's to read`;
+    const primaryKey = primaryKeyOf(entityName, def);
+    if (primaryKey.length !== 1)
+        return `'${entityName}' has a composite primary key, so no one id addresses a row`;
+    return {
+        def,
+        head: { entity: entityName, table: def.table, primaryKey: primaryKey[0], columns: Object.keys(def.fields.shape) },
+    };
+}
+/** The leading check, read back: a scope key, `{ key, entity, idFrom }`, or the clause it fails. */
+function plainPermission(permission) {
+    if (typeof permission === 'string')
+        return { key: permission };
+    const p = permission;
+    if (typeof p?.key === 'string' && typeof p.entity === 'string' && typeof p.idFrom === 'string') {
+        return { key: p.key, entity: p.entity, idFrom: p.idFrom };
+    }
+    return 'its permission is resolved, carried in a ref, or narrowed per row — the derived check is a scope key or `{ key, entity, idFrom }`';
+}
+function emitOf(decl) {
+    const e = decl.emits ?? {};
+    return {
+        type: e.type,
+        schemaVersion: e.schemaVersion,
+        piiClass: e.piiClass,
+        ...(typeof e.subjectId === 'string' ? { subjectId: e.subjectId } : {}),
+        payload: [...(e.payload ?? [])],
+    };
+}
+/** The input's fields, split by whether a caller may omit them. */
+function inputFields(decl) {
+    const required = [];
+    const optional = [];
+    for (const [field, schema] of Object.entries(decl.input?.shape ?? {})) {
+        (isOptionalSchema(schema) ? optional : required).push(field);
+    }
+    return { required, optional };
+}
+/** Clauses every derived shape shares: no per-row walk, no per-field projection, no bin access. */
+function commonClause(decl, kind) {
+    // The bin page's per-row check is `ctx.pageTrashed`'s own, so its `narrows` is part of its shape.
+    if (decl.narrows !== undefined && kind !== 'trashed') {
+        return 'it narrows per row (`narrows`), which is a walk the handler composes';
+    }
+    if (decl.gates !== undefined)
+        return 'it gates fields (`gates`), a projection the handler applies';
+    if (decl.inputOptional !== undefined)
+        return 'it declares `inputOptional`';
+    const reachesBin = (kind === 'delete' && decl.trashed === 'purges') || (kind === 'restore' && decl.trashed === 'admits');
+    if (decl.trashed !== undefined && !reachesBin) {
+        return `it declares \`trashed: '${String(decl.trashed)}'\` — reaching the bin is authored`;
+    }
+    return null;
+}
+function getPlan(decl, entities) {
+    if (decl.paged !== undefined)
+        return 'it is paged — a page is a `list`';
+    if (decl.emits !== undefined)
+        return 'it emits, and a read announces nothing';
+    // An invoke-only operation that emits nothing may still write — a silent transition reads the
+    // same from here — so a `get` is one the declaration itself SERVES as a read.
+    if (decl.http?.method !== 'GET')
+        return 'it is not served as GET, the method that says it only reads';
+    const name = entityOfOutput(decl.output, entities);
+    if (name === undefined)
+        return "its output is not one of this module's entities' own `fields`";
+    const base = derivableEntity(name, entities);
+    if (typeof base === 'string')
+        return base;
+    const { required, optional } = inputFields(decl);
+    if (required.length !== 1 || optional.length !== 0)
+        return 'its input is not the id alone';
+    const idFrom = required[0];
+    const permission = plainPermission(decl.permission);
+    if (typeof permission === 'string')
+        return permission;
+    if (permission.entity !== undefined && (permission.entity !== name || permission.idFrom !== idFrom)) {
+        return `its check narrows to '${permission.entity}' by '${String(permission.idFrom)}', not to the row it reads`;
+    }
+    if (permission.entity === undefined && base.def.trash !== undefined) {
+        return `'${name}' declares \`trash\`, and only a check narrowed to the row lets the host refuse a binned one`;
+    }
+    return { kind: 'get', ...base.head, permission, idFrom };
+}
+/** The column kinds a derived filter binds as they arrive — a boolean filter over a 0/1 column needs encoding. */
+const DERIVED_FILTER_KINDS = new Set(['string', 'number', 'literal', 'enum']);
+/** A derived page binds the input value as the filter, so the two must be the same kind. */
+function filterTypeIssue(decl, field, column, entity) {
+    const columnKind = baseDefOf(entity.fields.shape[column])?.type;
+    if (!columnKind || !DERIVED_FILTER_KINDS.has(columnKind)) {
+        return `filter column '${column}' is not a string, number or enum column`;
+    }
+    if (baseDefOf(decl.input?.shape[field])?.type !== columnKind) {
+        return `input field '${field}' is not the same type as filter column '${column}', so the handler maps it`;
+    }
+    return null;
+}
+/** One optional input as a declared filter of the page, or the clause it fails. */
+function optionalFilterOf(decl, field, filterable, entity) {
+    const column = snakeCaseField(field);
+    if (!filterable.has(column))
+        return `input field '${field}' is not a declared \`filterable\` column`;
+    if (inputDefaultIssue(decl.input?.shape[field]) !== null)
+        return `input field '${field}' has a default`;
+    return filterTypeIssue(decl, field, column, entity) ?? { field, column };
+}
+function listPlan(decl, entities) {
+    const over = decl.paged?.over;
+    if (over === undefined)
+        return 'it is not a kernel-composed page (`paged.over`)';
+    // A page is a read, matched as exactly as a `get`: a paged command that emits, or one served
+    // as anything but GET, writes as well as reads, and its handler is its own.
+    if (decl.emits !== undefined)
+        return 'it emits, and a read announces nothing';
+    if (decl.http?.method !== 'GET')
+        return 'it is not served as GET, the method that says it only reads';
+    const name = over.entity;
+    if (decl.output !== entities[name]?.fields)
+        return `its output is not '${name}'s own \`fields\``;
+    const base = derivableEntity(name, entities);
+    if (typeof base === 'string')
+        return base;
+    const permission = plainPermission(decl.permission);
+    if (typeof permission === 'string')
+        return permission;
+    const filterable = new Set(over.filterable ?? []);
+    const filters = [];
+    const { required, optional } = inputFields(decl);
+    let parent;
+    if (permission.entity !== undefined) {
+        const target = parentTarget(name, base.def, permission, entities, 'filters');
+        if (typeof target === 'string')
+            return target;
+        parent = target;
+        const { idFrom, column } = target;
+        if (!required.includes(idFrom) || !filterable.has(column)) {
+            return `the parent's id '${idFrom}' is not a required input filtering the declared \`filterable\` column '${column}'`;
+        }
+        const issue = filterTypeIssue(decl, idFrom, column, base.def);
+        if (issue)
+            return issue;
+        filters.push({ field: idFrom, column });
+    }
+    for (const field of required) {
+        if (field !== permission.idFrom)
+            return `input field '${field}' is required, and only the parent's id may be`;
+    }
+    let viewFrom;
+    for (const field of optional) {
+        if (field === VIEW_FIELD && base.def.archive !== undefined) {
+            const issue = viewIssue(decl.input?.shape[field], filterable);
+            if (issue)
+                return issue;
+            viewFrom = field;
+            continue;
+        }
+        const filter = optionalFilterOf(decl, field, filterable, base.def);
+        if (typeof filter === 'string')
+            return filter;
+        filters.push(filter);
+    }
+    return {
+        kind: 'list',
+        ...base.head,
+        permission,
+        filters,
+        total: decl.paged?.total === true,
+        ...(parent ? { parent } : {}),
+        ...(viewFrom !== undefined ? { viewFrom } : {}),
+    };
+}
+/**
+ * The parent a check narrows to, for a page of its children or a child created under it (#2157).
+ * The input's id must fill the LINK column `<parent>_id` — a filter or a value on any other column
+ * passes the check on one row and reads or writes another.
+ */
+function parentTarget(name, def, permission, entities, verb) {
+    const parent = permission.entity;
+    if (!(def.parents ?? []).includes(parent))
+        return `its check narrows to '${parent}', which is not a parent of '${name}'`;
+    const idFrom = permission.idFrom;
+    const column = snakeCaseField(idFrom);
+    const link = `${snakeCaseField(parent)}_id`;
+    if (column !== link) {
+        return `the parent's id '${idFrom}' ${verb} column '${column}', which is not the link to '${parent}' ('${link}')`;
+    }
+    const base = derivableEntity(parent, entities);
+    if (typeof base === 'string')
+        return base;
+    return { entity: parent, table: base.head.table, primaryKey: base.head.primaryKey, idFrom, column };
+}
+/** The input field a derived page of an archivable entity reads its view from (#119). */
+const VIEW_FIELD = 'view';
+/** The views `ctx.page` serves; the bin is its own read (`trashed`). */
+const PAGE_VIEWS = entityStateName.exclude(['trashed']).options;
+/** Why `view` cannot be passed to `ctx.page` as it arrives, or `null`. */
+function viewIssue(schema, filterable) {
+    if (filterable.has(VIEW_FIELD)) {
+        return `'${VIEW_FIELD}' is both the archive view and a declared \`filterable\` column, so the input means two things`;
+    }
+    if (inputDefaultIssue(schema) !== null)
+        return `input field '${VIEW_FIELD}' has a default`;
+    const base = baseDefOf(schema);
+    const values = base?.type === 'enum' ? Object.values(base.entries ?? {}).map(String).sort() : [];
+    if (values.join() !== [...PAGE_VIEWS].sort().join()) {
+        return `input field '${VIEW_FIELD}' is not \`z.enum(['active', 'archived'])\`, the views a page serves`;
+    }
+    return null;
+}
+/** The clauses a derived write shares: narrowed to the row it writes, announcing it, by that row's id. */
+function writeTarget(decl, entities) {
+    const permission = plainPermission(decl.permission);
+    if (typeof permission === 'string')
+        return permission;
+    if (permission.entity === undefined)
+        return 'its check is scope-wide, and a derived write is narrowed to the row it writes';
+    const name = permission.entity;
+    const base = derivableEntity(name, entities);
+    if (typeof base === 'string')
+        return base;
+    if (decl.emits?.entity !== name)
+        return `it does not emit about '${name}', the row it writes`;
+    if (decl.emits.entityIdFrom !== base.head.primaryKey) {
+        return `its event takes its subject from '${String(decl.emits.entityIdFrom)}', not the row's id '${base.head.primaryKey}'`;
+    }
+    const idFrom = permission.idFrom;
+    return { name, base, idFrom, permission: { key: permission.key, entity: name, idFrom } };
+}
+function updatePlan(decl, entities) {
+    if (decl.http?.method !== 'PATCH')
+        return 'it is not served as PATCH, the method whose absent fields stay untouched';
+    if (decl.patchException !== undefined)
+        return 'it declares `patchException`, so its body is not a field bag';
+    if (decl.paged !== undefined)
+        return 'it is paged';
+    const target = writeTarget(decl, entities);
+    if (typeof target === 'string')
+        return target;
+    const { name, base, idFrom } = target;
+    if (decl.output !== base.def.fields)
+        return `its output is not '${name}'s own \`fields\``;
+    if (decl.concurrency?.over !== name || decl.concurrency.idFrom !== idFrom) {
+        return `it declares no \`concurrency: { over: '${name}', idFrom: '${idFrom}' }\`, and a field bag without one loses updates`;
+    }
+    const { required, optional } = inputFields(decl);
+    if (required.length !== 1 || required[0] !== idFrom)
+        return `its input requires more than the id '${idFrom}'`;
+    if (optional.length === 0)
+        return 'its input has no field to write';
+    const columnShape = base.def.fields.shape;
+    const stamps = stampsOf(name, base.def);
+    const fields = [];
+    for (const field of optional) {
+        const target = writableColumn(decl, field, name, base.head.primaryKey, columnShape, stamps, UPDATE_WORDS);
+        if (typeof target === 'string')
+            return target;
+        const { column, columnSchema, fieldSchema } = target;
+        if (acceptsNull(fieldSchema) && !acceptsNull(columnSchema)) {
+            return `body field '${field}' accepts null, and column '${column}' cannot be cleared`;
+        }
+        fields.push({ field, column });
+    }
+    return {
+        kind: 'update',
+        ...base.head,
+        permission: target.permission,
+        idFrom,
+        fields,
+        emit: emitOf(decl),
+    };
+}
+const UPDATE_WORDS = {
+    field: 'body field',
+    onId: "would rewrite the row's id",
+    onEnum: 'a change of state is a lifecycle edge with its own operation',
+};
+const CREATE_WORDS = {
+    field: 'input field',
+    onId: "would set the row's id, which a create mints",
+    onEnum: "a row's first state is its lifecycle's, and authored",
+};
+/**
+ * The column one input field of a derived write fills, by its snake_case name — or the clause it
+ * fails: no such column, the id, a stamp, an enum, a kind the write cannot bind as it arrives, or
+ * a field of another type. Whether it may be empty is the caller's rule.
+ */
+function writableColumn(decl, field, name, primaryKey, columnShape, stamps, words) {
+    const column = snakeCaseField(field);
+    const columnSchema = columnShape[column];
+    if (columnSchema === undefined)
+        return `${words.field} '${field}' is not a column of '${name}'`;
+    if (column === primaryKey)
+        return `${words.field} '${field}' ${words.onId}`;
+    if (stamps[column] !== undefined)
+        return `${words.field} '${field}' writes '${column}', which is stamped`;
+    const fieldSchema = decl.input?.shape[field];
+    const kind = baseDefOf(columnSchema)?.type;
+    if (kind === 'enum')
+        return `column '${column}' is an enum — ${words.onEnum}`;
+    if (!kind || !DERIVED_WRITE_KINDS.has(kind))
+        return `column '${column}' is not a string or number column`;
+    if (baseDefOf(fieldSchema)?.type !== kind)
+        return `${words.field} '${field}' is not the same type as column '${column}'`;
+    return { column, columnSchema, fieldSchema };
+}
+/** The declared stamps, in declared order. */
+function stampList(stamps) {
+    return Object.entries(stamps).map(([column, kind]) => ({ column, kind }));
+}
+function deletePlan(decl, entities) {
+    if (decl.http?.method !== 'DELETE')
+        return 'it is not served as DELETE, the method that says it removes the row';
+    if (decl.paged !== undefined)
+        return 'it is paged';
+    const target = writeTarget(decl, entities);
+    if (typeof target === 'string')
+        return target;
+    const { name, base, idFrom } = target;
+    const outputKeys = Object.keys(decl.output?.shape ?? {}).sort();
+    if (outputKeys.join() !== 'deleted,id')
+        return 'its output is not `{ id, deleted }`';
+    const { required, optional } = inputFields(decl);
+    if (required.length !== 1 || required[0] !== idFrom || optional.length !== 0)
+        return `its input is not the id '${idFrom}' alone`;
+    const children = Object.keys(entities).filter((child) => (entities[child]?.parents ?? []).includes(name));
+    if (children.length > 0) {
+        return `${children.map((c) => `'${c}'`).join(', ')} declare${children.length === 1 ? 's' : ''} '${name}' as parent, so a delete would orphan them — a cascade is authored`;
+    }
+    return { kind: 'delete', ...base.head, permission: target.permission, idFrom, emit: emitOf(decl) };
+}
+/** A column a row may leave empty — what a derived create writes when no source names it. */
+const columnMayBeNull = (schema) => acceptsNull(schema) || isOptionalSchema(schema);
+function createPlan(decl, entities) {
+    if (decl.http?.method !== 'POST')
+        return 'it is not served as POST, the method that says it adds a row';
+    if (decl.paged !== undefined)
+        return 'it is paged';
+    if (decl.concurrency !== undefined)
+        return 'it declares `concurrency`, and a row that does not exist yet has no version';
+    const name = decl.emits?.entity;
+    if (typeof name !== 'string')
+        return 'it emits nothing, and a create announces the row it adds';
+    const base = derivableEntity(name, entities);
+    if (typeof base === 'string')
+        return base;
+    const { primaryKey } = base.head;
+    if (decl.output !== base.def.fields)
+        return `its output is not '${name}'s own \`fields\``;
+    if (decl.emits?.entityIdFrom !== primaryKey) {
+        return `its event takes its subject from '${String(decl.emits?.entityIdFrom)}', not the row's id '${primaryKey}'`;
+    }
+    const columnShape = base.def.fields.shape;
+    if (baseDefOf(columnShape[primaryKey])?.type !== 'string') {
+        return `'${name}'s id '${primaryKey}' is not a string column, so a minted id cannot fill it`;
+    }
+    const permission = plainPermission(decl.permission);
+    if (typeof permission === 'string')
+        return permission;
+    const { required, optional } = inputFields(decl);
+    let parent;
+    if (permission.entity !== undefined) {
+        const target = parentTarget(name, base.def, permission, entities, 'fills');
+        if (typeof target === 'string')
+            return target;
+        if (!required.includes(target.idFrom))
+            return `the parent's id '${target.idFrom}' is not a required input`;
+        if (baseDefOf(decl.input?.shape[target.idFrom])?.type !== baseDefOf(columnShape[target.column])?.type) {
+            return `input field '${target.idFrom}' is not the same type as link column '${target.column}'`;
+        }
+        parent = target;
+    }
+    const stamps = stampsOf(name, base.def);
+    // Every input field fills the column of its name — an input the row does not hold is one the
+    // handler does something else with.
+    const values = [];
+    for (const field of [...required, ...optional]) {
+        if (field === parent?.idFrom)
+            continue;
+        if (snakeCaseField(field) === parent?.column)
+            return `input field '${field}' writes the link column '${parent.column}'`;
+        const target = writableColumn(decl, field, name, primaryKey, columnShape, stamps, CREATE_WORDS);
+        if (typeof target === 'string')
+            return target;
+        const { column, columnSchema, fieldSchema } = target;
+        if ((optional.includes(field) || acceptsNull(fieldSchema)) && !columnMayBeNull(columnSchema)) {
+            return `input field '${field}' may be absent or null, and column '${column}' cannot be empty`;
+        }
+        values.push({ field, column });
+    }
+    const filled = new Set([primaryKey, ...(parent ? [parent.column] : []), ...Object.keys(stamps), ...values.map((v) => v.column)]);
+    for (const column of Object.keys(columnShape)) {
+        if (!filled.has(column) && !columnMayBeNull(columnShape[column])) {
+            return `column '${column}' is filled by nothing the model names — no input, stamp or parent link — and cannot be empty`;
+        }
+    }
+    const key = [...(base.def.key ?? [])];
+    const fromInput = new Set([...(parent ? [parent.column] : []), ...values.map((v) => v.column)]);
+    for (const column of key) {
+        if (!fromInput.has(column))
+            return `its natural key column '${column}' is not filled from the input, so no existing row can be matched by it`;
+    }
+    // A replay answers the row already holding the key. The check passed on the parent the caller
+    // named, so the key must pin that parent too, or the lookup answers another parent's row.
+    if (parent && key.length > 0 && !key.includes(parent.column)) {
+        return `its natural key does not include the link to '${parent.entity}' ('${parent.column}'), so a replay could answer another ${parent.entity}'s row`;
+    }
+    // A replay would also answer a row the kernel hides (#119, K-45): a binned one to a caller who
+    // may not see the bin, or an archived one the active view leaves out — and skipping hidden rows
+    // only moves the clash to the insert. What re-creating one means is the vertical's to decide.
+    const hides = [base.def.trash ? '`trash`' : null, base.def.archive ? '`archive`' : null].filter(Boolean);
+    if (key.length > 0 && hides.length > 0) {
+        return `'${name}' declares ${hides.join(' and ')} and a natural key, so a replay could answer a row the kernel hides — whether re-creating one restores it, unarchives it or refuses is the vertical's call, so its handler is written by hand`;
+    }
+    return {
+        kind: 'create',
+        ...base.head,
+        permission,
+        ...(parent ? { parent } : {}),
+        values,
+        stamps: stampList(stamps),
+        key,
+        emit: emitOf(decl),
+    };
+}
+/** The derived kinds that are one kernel move (#119, K-45), and which declaration gates each. */
+const MOVE_GATE = {
+    archive: 'archive',
+    unarchive: 'archive',
+    trash: 'trash',
+    restore: 'trash',
+};
+/**
+ * One kernel move: a POST of the id alone, narrowed to that row under the key the entity declares
+ * for it, answering `entityStateOutput` and declaring no event, since the kernel emits the move.
+ */
+function movePlan(kind) {
+    return (decl, entities) => {
+        if (decl.http?.method !== 'POST')
+            return 'it is not served as POST, the method a move of state is';
+        if (decl.paged !== undefined)
+            return 'it is paged';
+        if (decl.emits !== undefined)
+            return 'it declares `emits`, and the kernel announces the move itself';
+        if (decl.output !== entityStateOutput)
+            return 'its output is not `entityStateOutput`';
+        const permission = plainPermission(decl.permission);
+        if (typeof permission === 'string')
+            return permission;
+        if (permission.entity === undefined)
+            return 'its check is scope-wide, and a move is checked on the row it moves';
+        const name = permission.entity;
+        const base = derivableEntity(name, entities);
+        if (typeof base === 'string')
+            return base;
+        const gate = MOVE_GATE[kind];
+        const declared = base.def[gate]?.permission;
+        if (declared === undefined)
+            return `'${name}' declares no \`${gate}\``;
+        if (permission.key !== declared) {
+            return `its check is '${permission.key}', not the key '${name}' declares for its ${gate}, '${declared}'`;
+        }
+        const idFrom = permission.idFrom;
+        const { required, optional } = inputFields(decl);
+        if (required.length !== 1 || required[0] !== idFrom || optional.length !== 0)
+            return `its input is not the id '${idFrom}' alone`;
+        if (kind === 'restore' && decl.trashed !== 'admits') {
+            return "it does not declare `trashed: 'admits'`, and a restore is the move that reaches a binned row";
+        }
+        return { kind, ...base.head, permission: { key: declared, entity: name, idFrom }, idFrom };
+    };
+}
+/** The bin: `ctx.pageTrashed` over an entity that declares `trash`, which checks its key per row. */
+function trashedPlan(decl, entities) {
+    const over = decl.paged?.over;
+    if (over === undefined)
+        return 'it is not a kernel-composed page (`paged.over`)';
+    if (decl.emits !== undefined)
+        return 'it emits, and a read announces nothing';
+    if (decl.http?.method !== 'GET')
+        return 'it is not served as GET, the method that says it only reads';
+    if (decl.paged?.total !== undefined)
+        return 'it asks for a total, and a page of the bin carries none';
+    const name = over.entity;
+    if (decl.output !== entities[name]?.fields)
+        return `its output is not '${name}'s own \`fields\``;
+    const base = derivableEntity(name, entities);
+    if (typeof base === 'string')
+        return base;
+    const key = base.def.trash?.permission;
+    if (key === undefined)
+        return `'${name}' declares no \`trash\``;
+    // `ctx.pageTrashed` checks the trash key on every row: a leading check on top would deny the
+    // person whose key is narrowed to the rows they binned, and say nothing the walk does not.
+    if (decl.permission !== undefined)
+        return 'it declares a leading check, and the bin is checked row by row';
+    // `unchecked` says the operation checks nothing, which a bin walked under its key is not.
+    const narrows = decl.narrows;
+    if (narrows?.unchecked !== undefined || narrows?.checks?.length !== 1 || narrows.checks[0] !== key) {
+        return `it does not declare \`narrows\` checking exactly '${key}', the key the bin is walked under`;
+    }
+    const filterable = new Set(over.filterable ?? []);
+    const filters = [];
+    const { required, optional } = inputFields(decl);
+    if (required.length !== 0)
+        return `input field '${required[0]}' is required, and a page of the bin takes filters only`;
+    for (const field of optional) {
+        const filter = optionalFilterOf(decl, field, filterable, base.def);
+        if (typeof filter === 'string')
+            return filter;
+        filters.push(filter);
+    }
+    return { kind: 'trashed', ...base.head, permission: { key }, filters };
+}
+const PLANNERS = {
+    get: getPlan,
+    list: listPlan,
+    update: updatePlan,
+    delete: deletePlan,
+    create: createPlan,
+    archive: movePlan('archive'),
+    unarchive: movePlan('unarchive'),
+    trash: movePlan('trash'),
+    restore: movePlan('restore'),
+    trashed: trashedPlan,
+};
+/** The plan for one shape, or the clause the declaration fails — the shared clauses first. */
+function planFor(kind, decl, entities) {
+    return commonClause(decl, kind) ?? PLANNERS[kind](decl, entities);
+}
+/**
+ * The shape the platform could derive this operation's handler as, read off its declaration and
+ * the module's entities alone — `undefined` when it matches none of `DerivedKind`. Pure: this
+ * classifies, and `defineOperations` is what refuses. The first shape that matches is answered:
+ * a `get` is served as GET and not paged, a `list` is paged, an `update` is a PATCH that emits, a
+ * `delete` is a DELETE answering `{ id, deleted }`, a `create` is a POST that emits. The moves are
+ * the exception (`derivedKindsOf`).
+ */
+export function derivationOf(decl, entities) {
+    for (const kind of DERIVED_KINDS) {
+        const plan = planFor(kind, decl, entities);
+        if (typeof plan !== 'string')
+            return plan;
+    }
+    return undefined;
+}
+/**
+ * Every shape a declaration matches. One, except for a move (#119): archive and unarchive declare
+ * the same shape, so a hand-written one is named as both and `derive` says which it is.
+ */
+function derivedKindsOf(decl, entities) {
+    return DERIVED_KINDS.filter((kind) => typeof planFor(kind, decl, entities) !== 'string');
+}
+/**
+ * A handler the platform could write is either written by it or excused, by name (#1773).
+ *
+ * Runs at module load, beside the PATCH and paged gates, and for their reason: it fires in every
+ * build, test, dev server and `lint:model --check`, so it cannot be true only of the modules a
+ * tool knew about. A derivable operation declaring neither `derive` nor `authored` is refused;
+ * so are a `derive` whose shape does not match (with the clause that fails), an `authored` on
+ * an operation nothing could derive, and the two together.
+ */
+function assertHandlersDeclared(operations, entities) {
+    for (const [name, op] of Object.entries(operations)) {
+        const decl = op;
+        const { derive, authored } = decl;
+        if (derive !== undefined && authored !== undefined) {
+            throw new Error(`model: '${name}' declares both \`derive\` and \`authored\` — a handler is written by the platform or by you, not both.\n` +
+                '  Remedy: keep `derive` and delete the handler, or keep `authored` and drop `derive`.');
+        }
+        if (authored !== undefined && (typeof authored !== 'string' || authored.trim() === '')) {
+            throw new Error(`model: '${name}' declares \`authored\` without a reason.\n` +
+                '  Remedy: say what the derived handler would get wrong here, or declare `derive` and delete the handler.');
+        }
+        if (derive !== undefined) {
+            if (!DERIVED_KINDS.includes(derive)) {
+                throw new Error(`model: '${name}' declares \`derive: '${String(derive)}'\` — the derivable shapes are ${DERIVED_KINDS.join(', ')}.\n` +
+                    '  Remedy: declare one of them, or drop `derive` and write the handler.');
+            }
+            const plan = planFor(derive, decl, entities);
+            if (typeof plan === 'string') {
+                throw new Error(`model: '${name}' declares \`derive: '${String(derive)}'\`, but ${plan}.\n` +
+                    '  Remedy: make the declaration the shape it derives, or drop `derive` and write the handler.');
+            }
+            DERIVATION_PLANS.set(op, plan);
+            continue;
+        }
+        const plan = derivationOf(decl, entities);
+        if (plan === undefined) {
+            if (authored !== undefined) {
+                throw new Error(`model: '${name}' declares \`authored\`, but nothing about it is derivable — it matches none of ` +
+                    `${DERIVED_KINDS.join(', ')}, so every handler for it is authored already.\n` +
+                    '  Remedy: remove `authored`.');
+            }
+            continue;
+        }
+        if (authored !== undefined)
+            continue;
+        const kinds = derivedKindsOf(decl, entities);
+        const named = kinds.map((k) => `\`${k}\``).join(' or ');
+        const derives = kinds.map((k) => `\`derive: '${k}'\``).join(' or ');
+        throw new Error(`model: '${name}' is derivable from the model as ${named} over '${plan.entity}', and declares neither ` +
+            '`derive` nor `authored`.\n' +
+            `  A hand-written ${plan.kind} restates its declaration, and each restatement drifts (#1773).\n` +
+            `  Remedy: declare ${derives} and delete its handler, or declare ` +
+            `\`authored: '<why the derived ${plan.kind} is wrong here>'\`.`);
+    }
+}
 /**
  * The concurrency each operation declares, for the host (#129).
  *
- * Handed over beside `operationInputs` and read the same way — the adapter
+ * Handed over as `operations.concurrency`, beside the inputs, and read the same way — the adapter
  * compares versions from this map rather than each handler being trusted to. Same
  * argument as the parse: one place that cannot be forgotten beats a rule every
  * new operation has to remember.
@@ -497,8 +1130,8 @@ export function operationConcurrencyOf(operations) {
  * name → the entity each operation addresses by id, for the host (#119).
  *
  * Every operation whose leading check is `{ entity, idFrom }`, whether or not its entity
- * declares `trash` — the host keeps the ones whose entity does. Handed over beside
- * `operationInputs`, and required by the host from any module with a trashable entity, so a
+ * declares `trash` — the host keeps the ones whose entity does. Carried by `operations.inputs`,
+ * and required by the host from any module with a trashable entity, so a
  * module cannot leave its binned entities reachable by forgetting the line.
  */
 export function operationTargetsOf(operations) {
@@ -1143,4 +1776,21 @@ export function defineEngineRoutes(operations) {
         return out;
     };
 }
+/**
+ * Declare an app's hand-handled routes (#2170).
+ *
+ * ```ts
+ * export const routes = defineRoutes({
+ *   'dashboard/list-findings': {
+ *     summary: "This team's findings, most recently seen first",
+ *     input: z.object({ status: findingStatus.optional() }),
+ *     output: z.object({ available: z.boolean(), entries: z.array(findingEntry) }),
+ *     http: { method: 'GET', path: '/findings' },
+ *   },
+ * });
+ * ```
+ */
+export function defineRoutes(routes) {
+    return routes;
+}
 //# sourceMappingURL=operations.js.map