@happyvertical/smrt-planner 0.0.0-stage → 0.0.2

package/dist/recipes/plumbing.js

@@ -0,0 +1,185 @@
+/**
+ * Plumbing vs feature. The Features tab lists models a visitor can add to the
+ * menu; most of the ~220 uncovered models are rows that only make sense inside
+ * another model (a line item, a link table, a lookup list), so they are hidden
+ * unless "Show all" is on. The rules are data-driven where the catalog allows:
+ *
+ * 1. Extends a junction/association base (`SmrtJunction`, `SmrtJunctionBase`,
+ *    `SmrtPolymorphicAssociation`). The catalog keeps `extends` only for
+ *    same-package STI parents, so this fires once the generator carries bases.
+ * 2. Looks like a link table: two or more foreign keys and at most one other
+ *    own field (`GroupMember`, `RolePermission`, `ProfileMetadata`).
+ * 3. Child/extension record, by name suffix: `Metafield`, `Metadata`,
+ *    `Association`, `LineItem`, `Allocation`, `Revision`, `Attachment`,
+ *    `Snapshot`, `Completion`, `Override`, `Alias`. Each appears in the catalog
+ *    only as a dependent of a parent model (`InvoiceLineItem`,
+ *    `ContentContributionRevision`, `CampaignMetricSnapshot`).
+ * 4. Tiny lookup list: a name ending `Status` or `Type` with at most three
+ *    non-system fields (`AssetStatus`, `PlaceType`, `ProfileType`). Richer
+ *    types such as `ContentContributionType` stay features.
+ */
+export const JUNCTION_BASES = [
+    'SmrtJunction',
+    'SmrtJunctionBase',
+    'SmrtPolymorphicAssociation',
+];
+export const CHILD_SUFFIXES = [
+    'Metafield',
+    'Metadata',
+    'Association',
+    'LineItem',
+    'Allocation',
+    'Revision',
+    'Attachment',
+    'Snapshot',
+    'Completion',
+    'Override',
+    'Alias',
+];
+export const LOOKUP_SUFFIXES = ['Status', 'Type'];
+export const LOOKUP_MAX_FIELDS = 3;
+export const LINK_MIN_REFS = 2;
+export const LINK_MAX_OTHER_FIELDS = 1;
+const REF_TYPES = new Set(['foreignKey', 'crossPackageRef']);
+/** The reason a model is plumbing, or null when it is a feature. */
+export function plumbingReason(model) {
+    const base = model.extends?.split(':').pop();
+    if (base && JUNCTION_BASES.includes(base))
+        return 'junction';
+    const own = model.fields.filter((f) => !f.system);
+    const refs = own.filter((f) => REF_TYPES.has(f.type)).length;
+    if (refs >= LINK_MIN_REFS && own.length - refs <= LINK_MAX_OTHER_FIELDS) {
+        return 'link';
+    }
+    if (CHILD_SUFFIXES.some((s) => model.name.endsWith(s)))
+        return 'child';
+    if (own.length <= LOOKUP_MAX_FIELDS &&
+        LOOKUP_SUFFIXES.some((s) => model.name.endsWith(s))) {
+        return 'lookup';
+    }
+    return null;
+}
+export function isPlumbing(model) {
+    return plumbingReason(model) !== null;
+}
+/** Plumbing reasons that make a model a dependent record of what it points at. */
+const CHILD_REASONS = new Set(['junction', 'link', 'child']);
+/** A field's `related` as a qualified name, given the package it is declared in. */
+function qualify(related, ownerId) {
+    return related.includes(':')
+        ? related
+        : `${ownerId.slice(0, ownerId.lastIndexOf(':'))}:${related}`;
+}
+/**
+ * The model and its STI ancestors, nearest first (`ProductionOrder` extends
+ * `Contract`, whose `ContractLineItem` rows belong to every Contract subtype).
+ */
+function lineage(byId, modelId) {
+    const ids = [];
+    let current = byId.get(modelId);
+    while (current && !ids.includes(current.id)) {
+        ids.push(current.id);
+        current = current.extends
+            ? byId.get(qualify(current.extends, current.id))
+            : undefined;
+    }
+    return ids;
+}
+/**
+ * Child records of a model, found from the catalog: models with a foreign key
+ * to the model (or to a model it extends) that are line items, allocations,
+ * link tables and the like (`plumbingReason` of junction, link or child, never
+ * a plain lookup list). They ride along with the model and have no menu entry.
+ */
+export function childModels(catalog, modelId) {
+    const all = catalog.packages.flatMap((p) => p.models);
+    const byId = new Map(all.map((m) => [m.id, m]));
+    const parents = new Set(lineage(byId, modelId));
+    if (!parents.size)
+        return [];
+    return all.filter((candidate) => {
+        if (parents.has(candidate.id))
+            return false;
+        const reason = plumbingReason(candidate);
+        if (!reason || !CHILD_REASONS.has(reason))
+            return false;
+        return candidate.fields.some((f) => REF_TYPES.has(f.type) &&
+            f.related &&
+            parents.has(qualify(f.related, candidate.id)));
+    });
+}
+function linkTo(candidate, parents) {
+    const field = candidate.fields.find((f) => REF_TYPES.has(f.type) &&
+        f.related &&
+        parents.has(qualify(f.related, candidate.id)));
+    return field ? { model: candidate, fk: field.name } : undefined;
+}
+/**
+ * The records that live inside a model's own record view. When the model is in
+ * a recipe, a child is a model the recipe lists but gives no menu entry (so it
+ * has no page of its own) whose foreign key targets the model or a class it
+ * extends: `ContractLineItem` under every Contract subtype, `InvoiceLineItem`
+ * and `PaymentAllocation` under Invoice, `JournalEntry` under Journal. A model
+ * in no recipe (a Feature) falls back to {@link childModels}.
+ */
+export function childLinks(catalog, recipes, modelId) {
+    const all = catalog.packages.flatMap((p) => p.models);
+    const byId = new Map(all.map((m) => [m.id, m]));
+    const parents = new Set(lineage(byId, modelId));
+    if (!parents.size)
+        return [];
+    const scoped = recipes.filter((r) => r.models.includes(modelId));
+    if (!scoped.length) {
+        return childModels(catalog, modelId).flatMap((m) => {
+            const link = linkTo(m, parents);
+            return link ? [link] : [];
+        });
+    }
+    const found = new Map();
+    for (const recipe of scoped) {
+        const navIds = new Set(recipe.nav.map((e) => e.model));
+        for (const id of recipe.models) {
+            const candidate = byId.get(id);
+            if (!candidate || navIds.has(id) || parents.has(id) || found.has(id)) {
+                continue;
+            }
+            const link = linkTo(candidate, parents);
+            if (link)
+                found.set(id, link);
+        }
+    }
+    return [...found.values()];
+}
+/** Does any recipe give the model a menu entry of its own? */
+export function hasNavPage(recipes, modelId) {
+    return recipes.some((r) => r.nav.some((e) => e.model === modelId));
+}
+/**
+ * Title of a child table: the child's name without the parent's prefix,
+ * pluralised ("ContractLineItem" under Agreement/Contract is "Line items").
+ */
+export function childTitle(childName, parentNames) {
+    let name = childName;
+    for (const parent of parentNames) {
+        if (name.length > parent.length && name.startsWith(parent)) {
+            name = name.slice(parent.length);
+            break;
+        }
+    }
+    const spaced = name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase();
+    const plural = /[^aeiou]y$/.test(spaced)
+        ? `${spaced.slice(0, -1)}ies`
+        : /(s|x|ch|sh)$/.test(spaced)
+            ? `${spaced}es`
+            : `${spaced}s`;
+    return plural.charAt(0).toUpperCase() + plural.slice(1);
+}
+/** Names of the model and its STI ancestors, for {@link childTitle}. */
+export function lineageNames(catalog, modelId) {
+    const all = catalog.packages.flatMap((p) => p.models);
+    const byId = new Map(all.map((m) => [m.id, m]));
+    return lineage(byId, modelId).flatMap((id) => {
+        const m = byId.get(id);
+        return m ? [m.name] : [];
+    });
+}

package/dist/recipes/policy.d.ts

@@ -0,0 +1,118 @@
+import type { CatalogField, CatalogModel } from '../catalog/types.ts';
+import type { ExposureSurface, RecipeModelHints } from './types.ts';
+/**
+ * Field policies in the vocabulary of `@happyvertical/smrt-fields`
+ * (`FieldPolicyOptions`, `FieldPolicyVisibility`). The shapes are mirrored
+ * here, not imported: the package becomes a dependency with PGlite in
+ * smrt-planner#4, when these rows become real `_smrt_field_policies` rows.
+ */
+export type FieldPolicyVisibility = 'basic' | 'advanced' | 'hidden';
+/**
+ * One stored policy row, as `FieldPolicyOptions` names it. Only the keys a
+ * person changed are present; everything else inherits from the code seed (the
+ * catalog's `ui` hints plus the recipe's hints).
+ */
+export interface FieldPolicyRow {
+    /** Qualified class name, `@scope/pkg:Class`. */
+    objectRef: string;
+    fieldName: string;
+    /** The planner writes app-scope rows only. */
+    scopeType: 'app';
+    /** ENCODED channel: JSON text exactly as the column stores it (`'"Net 30"'`). */
+    defaultValue?: string | null;
+    visibility?: FieldPolicyVisibility | null;
+    help?: string | null;
+    label?: string | null;
+    displayOrder?: number | null;
+    locked?: boolean | null;
+}
+/** A field's merged policy: catalog hints, then recipe hints, then rows. */
+export interface ResolvedField {
+    field: CatalogField;
+    visibility: FieldPolicyVisibility;
+    label: string;
+    help: string | null;
+    order: number;
+    group: string | null;
+    /** Policy-locked: rows may not change it. */
+    locked: boolean;
+    required: boolean;
+    hasDefault: boolean;
+    default: unknown;
+    /** The required-field invariant forced `basic`. */
+    visibilityForced?: boolean;
+}
+/** A field as the generated list and form show it. */
+export interface ViewField extends CatalogField {
+    label: string;
+    help?: string;
+}
+/** Fields a person edits: everything the framework does not manage. */
+export declare function policyFields(model: CatalogModel): CatalogField[];
+/**
+ * The single-table-inheritance discriminator: an enumerated `...Type` field of
+ * a subclass that lists the model's own snake_case name, like `contractType`
+ * on a ProductionOrder. A root class's own enumeration (a Product's
+ * `productType`: product, material) is data, not a discriminator. It tells the classes of a shared table
+ * apart, so a form never offers it.
+ */
+export declare function isDiscriminatorField(model: CatalogModel, field: CatalogField): boolean;
+/**
+ * Merge a model's field policies: catalog `ui` hints and the recipe's hints are
+ * the code seed, `rows` (app scope) layer on top. A locked field ignores rows
+ * unless a row explicitly unlocks it. Result is ordered by `order`, then by
+ * declaration.
+ */
+export declare function resolveFields(model: CatalogModel, hints: RecipeModelHints | undefined, rows?: readonly FieldPolicyRow[]): ResolvedField[];
+/** The fields the generated list and form show: basic ones, policy applied. */
+export declare function viewFields(resolved: readonly ResolvedField[]): ViewField[];
+/**
+ * Defaults for fields the views do not show (hidden or off), so records still
+ * carry them: the `contractType` discriminator of a shared Contract table.
+ */
+export declare function backgroundDefaults(resolved: readonly ResolvedField[]): Record<string, unknown>;
+/** What the options form edits for one field. */
+export interface FieldDraft {
+    /** The "use this field" switch. */
+    use: boolean;
+    label: string;
+    help: string;
+    default: unknown;
+    order: number;
+}
+export type ExposureDraft = Record<ExposureSurface, boolean>;
+export interface ModelDraft {
+    fields: Record<string, FieldDraft>;
+    exposure: ExposureDraft;
+}
+export declare const SURFACES: readonly ExposureSurface[];
+export declare const SURFACE_LABEL: Record<ExposureSurface, string>;
+export declare function surfaceAvailable(model: CatalogModel, surface: ExposureSurface): boolean;
+export interface ExposureState {
+    /** The class declares this surface. */
+    available: boolean;
+    /** Currently exposed. */
+    on: boolean;
+    /** Cannot be changed: the class has none, or the recipe already narrowed it. */
+    locked: boolean;
+}
+/**
+ * Exposure can only be narrowed: a surface is on when the class declares it,
+ * the recipe did not narrow it off, and the person did not switch it off.
+ */
+export declare function resolveExposure(model: CatalogModel, hints: RecipeModelHints | undefined, narrowed?: readonly ExposureSurface[]): Record<ExposureSurface, ExposureState>;
+/** The model as exposed: narrowed surfaces list nothing. */
+export declare function narrowModel(model: CatalogModel, exposure: Record<ExposureSurface, ExposureState>): CatalogModel;
+/** Fields the options form lets a person switch off or edit. */
+export declare function formFields(model: CatalogModel, hints: RecipeModelHints | undefined, rows?: readonly FieldPolicyRow[]): ResolvedField[];
+/** Can the "use this field" switch move? Required and locked fields cannot. */
+export declare function isFieldLockedOn(r: ResolvedField): boolean;
+export declare function draftFrom(model: CatalogModel, hints: RecipeModelHints | undefined, rows: readonly FieldPolicyRow[], narrowed: readonly ExposureSurface[]): ModelDraft;
+/**
+ * Turn a draft into app-scope policy rows. Only differences from the code seed
+ * are written, so an untouched form writes nothing and a row never repeats a
+ * value the seed already gives.
+ */
+export declare function rowsFromDraft(model: CatalogModel, hints: RecipeModelHints | undefined, draft: ModelDraft): FieldPolicyRow[];
+/** The surfaces a draft switches off, beyond what the recipe already narrowed. */
+export declare function narrowedFromDraft(model: CatalogModel, hints: RecipeModelHints | undefined, draft: ModelDraft): ExposureSurface[];

package/dist/recipes/policy.js

@@ -0,0 +1,268 @@
+import { fieldLabel } from "../data/format.js";
+/** Fields a person edits: everything the framework does not manage. */
+export function policyFields(model) {
+    return model.fields.filter((f) => !f.system);
+}
+const snakeCase = (name) => name.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+/**
+ * The single-table-inheritance discriminator: an enumerated `...Type` field of
+ * a subclass that lists the model's own snake_case name, like `contractType`
+ * on a ProductionOrder. A root class's own enumeration (a Product's
+ * `productType`: product, material) is data, not a discriminator. It tells the classes of a shared table
+ * apart, so a form never offers it.
+ */
+export function isDiscriminatorField(model, field) {
+    return (/Type$/.test(field.name) &&
+        Array.isArray(field.enum) &&
+        field.enum.length > 0 &&
+        Boolean(model.extends) &&
+        field.enum.includes(snakeCase(model.name)));
+}
+/** The cold-start rule: with no `ui.basic` marker anywhere, all fields are basic. */
+function hasBasicMarkers(fields) {
+    return fields.some((f) => f.ui?.basic === true);
+}
+function usableRequiredDefault(value) {
+    return value !== null && value !== undefined && value !== '';
+}
+function parseDefault(encoded) {
+    if (encoded === null || encoded === undefined)
+        return null;
+    try {
+        return { value: JSON.parse(encoded) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Merge a model's field policies: catalog `ui` hints and the recipe's hints are
+ * the code seed, `rows` (app scope) layer on top. A locked field ignores rows
+ * unless a row explicitly unlocks it. Result is ordered by `order`, then by
+ * declaration.
+ */
+export function resolveFields(model, hints, rows = []) {
+    const fields = policyFields(model);
+    const markers = hasBasicMarkers(fields);
+    const own = new Map(rows.filter((r) => r.objectRef === model.id).map((r) => [r.fieldName, r]));
+    const resolved = fields.map((field, index) => {
+        const hint = hints?.fields?.[field.name] ?? {};
+        const discriminator = isDiscriminatorField(model, field);
+        let visibility = hint.visibility ??
+            (discriminator
+                ? 'hidden'
+                : !markers || field.ui?.basic === true
+                    ? 'basic'
+                    : 'advanced');
+        let label = hint.label ?? fieldLabel(field);
+        let help = hint.help ?? null;
+        let order = hint.order ?? field.ui?.order ?? index;
+        let locked = hint.locked ?? field.ui?.locked ?? discriminator;
+        const ownType = snakeCase(model.name);
+        const fallback = field.default !== undefined
+            ? field.default
+            : discriminator && field.enum?.includes(ownType)
+                ? ownType
+                : undefined;
+        let hasDefault = 'default' in hint || fallback !== undefined;
+        let value = 'default' in hint ? hint.default : fallback;
+        const row = own.get(field.name);
+        if (row && (!locked || row.locked === false)) {
+            if (row.visibility)
+                visibility = row.visibility;
+            if (row.label)
+                label = row.label;
+            if (row.help !== undefined)
+                help = row.help || null;
+            if (typeof row.displayOrder === 'number')
+                order = row.displayOrder;
+            const parsed = parseDefault(row.defaultValue);
+            if (parsed) {
+                hasDefault = true;
+                value = parsed.value;
+            }
+            if (typeof row.locked === 'boolean')
+                locked = row.locked;
+        }
+        // The required-field invariant: a required field may only leave the basic
+        // tier when a usable default fills it in.
+        let visibilityForced;
+        const required = hint.required ?? field.required;
+        if (required &&
+            visibility !== 'basic' &&
+            !(hasDefault && usableRequiredDefault(value))) {
+            visibility = 'basic';
+            visibilityForced = true;
+        }
+        return {
+            field,
+            visibility,
+            label,
+            help,
+            order,
+            group: field.ui?.group ?? null,
+            locked,
+            required,
+            hasDefault,
+            default: value,
+            ...(visibilityForced ? { visibilityForced } : {}),
+        };
+    });
+    return resolved
+        .map((entry, index) => ({ entry, index }))
+        .sort((a, b) => a.entry.order - b.entry.order || a.index - b.index)
+        .map(({ entry }) => entry);
+}
+function primitive(value) {
+    return typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        value === null
+        ? value
+        : undefined;
+}
+/** The fields the generated list and form show: basic ones, policy applied. */
+export function viewFields(resolved) {
+    return resolved
+        .filter((r) => r.visibility === 'basic')
+        .map((r) => {
+        const { default: _unused, ...rest } = r.field;
+        const fallback = r.hasDefault ? primitive(r.default) : undefined;
+        return {
+            ...rest,
+            required: r.required,
+            ...(fallback !== undefined ? { default: fallback } : {}),
+            label: r.label,
+            ...(r.help ? { help: r.help } : {}),
+        };
+    });
+}
+/**
+ * Defaults for fields the views do not show (hidden or off), so records still
+ * carry them: the `contractType` discriminator of a shared Contract table.
+ */
+export function backgroundDefaults(resolved) {
+    const values = {};
+    for (const r of resolved) {
+        if (r.visibility !== 'basic' && r.hasDefault && r.default !== undefined) {
+            values[r.field.name] = r.default;
+        }
+    }
+    return values;
+}
+export const SURFACES = ['api', 'mcp', 'cli'];
+export const SURFACE_LABEL = {
+    api: 'REST',
+    mcp: 'MCP',
+    cli: 'CLI',
+};
+export function surfaceAvailable(model, surface) {
+    const count = surface === 'api'
+        ? model.rest.length
+        : surface === 'mcp'
+            ? model.mcp.length
+            : model.cli.length;
+    return count > 0;
+}
+/**
+ * Exposure can only be narrowed: a surface is on when the class declares it,
+ * the recipe did not narrow it off, and the person did not switch it off.
+ */
+export function resolveExposure(model, hints, narrowed = []) {
+    const result = {};
+    for (const surface of SURFACES) {
+        const available = surfaceAvailable(model, surface);
+        const recipeOff = hints?.exposure?.[surface] === false;
+        result[surface] = {
+            available,
+            on: available && !recipeOff && !narrowed.includes(surface),
+            locked: !available || recipeOff,
+        };
+    }
+    return result;
+}
+/** The model as exposed: narrowed surfaces list nothing. */
+export function narrowModel(model, exposure) {
+    const mcp = exposure.mcp.on;
+    return {
+        ...model,
+        rest: exposure.api.on ? model.rest : [],
+        mcp: mcp ? model.mcp : [],
+        cli: exposure.cli.on ? model.cli : [],
+        methods: model.methods.map((m) => ({
+            ...m,
+            aiCallable: m.aiCallable && mcp,
+        })),
+    };
+}
+/** Fields the options form lets a person switch off or edit. */
+export function formFields(model, hints, rows = []) {
+    return resolveFields(model, hints, rows).filter((r) => hints?.fields?.[r.field.name]?.visibility !== 'hidden');
+}
+/** Can the "use this field" switch move? Required and locked fields cannot. */
+export function isFieldLockedOn(r) {
+    return r.required || r.locked;
+}
+export function draftFrom(model, hints, rows, narrowed) {
+    const fields = {};
+    for (const r of formFields(model, hints, rows)) {
+        fields[r.field.name] = {
+            use: r.visibility === 'basic',
+            label: r.label,
+            help: r.help ?? '',
+            default: r.hasDefault ? r.default : null,
+            order: r.order,
+        };
+    }
+    const exposure = resolveExposure(model, hints, narrowed);
+    return {
+        fields,
+        exposure: {
+            api: exposure.api.on,
+            mcp: exposure.mcp.on,
+            cli: exposure.cli.on,
+        },
+    };
+}
+const sameJson = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+/**
+ * Turn a draft into app-scope policy rows. Only differences from the code seed
+ * are written, so an untouched form writes nothing and a row never repeats a
+ * value the seed already gives.
+ */
+export function rowsFromDraft(model, hints, draft) {
+    const seed = formFields(model, hints);
+    const rows = [];
+    for (const base of seed) {
+        const edited = draft.fields[base.field.name];
+        if (!edited || base.locked)
+            continue;
+        const row = {
+            objectRef: model.id,
+            fieldName: base.field.name,
+            scopeType: 'app',
+        };
+        const use = isFieldLockedOn(base) ? true : edited.use;
+        const seedUse = base.visibility === 'basic';
+        if (use !== seedUse)
+            row.visibility = use ? 'basic' : 'hidden';
+        if (edited.label.trim() && edited.label !== base.label) {
+            row.label = edited.label.trim();
+        }
+        if (edited.help !== (base.help ?? ''))
+            row.help = edited.help || null;
+        if (!sameJson(edited.default, base.hasDefault ? base.default : null)) {
+            row.defaultValue = JSON.stringify(edited.default ?? null);
+        }
+        if (edited.order !== base.order)
+            row.displayOrder = edited.order;
+        if (Object.keys(row).length > 3)
+            rows.push(row);
+    }
+    return rows;
+}
+/** The surfaces a draft switches off, beyond what the recipe already narrowed. */
+export function narrowedFromDraft(model, hints, draft) {
+    const seed = resolveExposure(model, hints);
+    return SURFACES.filter((surface) => seed[surface].on && !draft.exposure[surface]);
+}

package/dist/recipes/resolve.d.ts

@@ -0,0 +1,19 @@
+import type { Recipe } from './types.ts';
+/** Sorted and de-duplicated, so the same selection is always the same URL. */
+export declare function normalizeRecipes(ids: Iterable<string>): string[];
+/**
+ * `ids` plus every recipe they transitively `require`, as a sorted set. A
+ * `requiresAny` list with none of its alternatives present adds the first
+ * known one.
+ */
+export declare function withRequirements(ids: Iterable<string>, recipes: ReadonlyMap<string, Recipe>): string[];
+/**
+ * Selected recipes that would force any of `ids` back on if they were all
+ * removed: they require one directly, or `ids` hold the last alternative of
+ * one of their `requiresAny` lists.
+ */
+export declare function removalBlockers(ids: readonly string[], selected: readonly string[], recipes: ReadonlyMap<string, Recipe>): string[];
+/** Ids of the selected recipes that require `id` and so keep it on. */
+export declare function recipesRequiring(id: string, selected: readonly string[], recipes: ReadonlyMap<string, Recipe>): string[];
+/** Keep only ids that name a known recipe. */
+export declare function knownRecipes(ids: Iterable<string>, recipes: ReadonlyMap<string, Recipe>): string[];

package/dist/recipes/resolve.js

@@ -0,0 +1,65 @@
+/** Sorted and de-duplicated, so the same selection is always the same URL. */
+export function normalizeRecipes(ids) {
+    return [...new Set(ids)].sort();
+}
+/**
+ * `ids` plus every recipe they transitively `require`, as a sorted set. A
+ * `requiresAny` list with none of its alternatives present adds the first
+ * known one.
+ */
+export function withRequirements(ids, recipes) {
+    const result = new Set();
+    const visit = (id) => {
+        const recipe = recipes.get(id);
+        if (!recipe || result.has(id))
+            return;
+        result.add(id);
+        for (const required of recipe.requires)
+            visit(required);
+    };
+    for (const id of ids)
+        visit(id);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const id of [...result]) {
+            for (const alternatives of recipes.get(id)?.requiresAny ?? []) {
+                if (alternatives.some((alt) => result.has(alt)))
+                    continue;
+                const first = alternatives.find((alt) => recipes.has(alt));
+                if (first) {
+                    visit(first);
+                    changed = true;
+                }
+            }
+        }
+    }
+    return normalizeRecipes(result);
+}
+/**
+ * Selected recipes that would force any of `ids` back on if they were all
+ * removed: they require one directly, or `ids` hold the last alternative of
+ * one of their `requiresAny` lists.
+ */
+export function removalBlockers(ids, selected, recipes) {
+    const removing = new Set(ids);
+    const remaining = selected.filter((id) => !removing.has(id));
+    const keep = new Set(remaining);
+    return remaining.filter((other) => {
+        const recipe = recipes.get(other);
+        if (!recipe)
+            return false;
+        if (recipe.requires.some((id) => removing.has(id)))
+            return true;
+        return (recipe.requiresAny ?? []).some((alternatives) => alternatives.some((alt) => removing.has(alt)) &&
+            !alternatives.some((alt) => keep.has(alt)));
+    });
+}
+/** Ids of the selected recipes that require `id` and so keep it on. */
+export function recipesRequiring(id, selected, recipes) {
+    return removalBlockers([id], selected, recipes);
+}
+/** Keep only ids that name a known recipe. */
+export function knownRecipes(ids, recipes) {
+    return normalizeRecipes([...ids].filter((id) => recipes.has(id)));
+}

package/dist/recipes/scope.d.ts

@@ -0,0 +1,25 @@
+import type { RecipeNavTarget } from './index.ts';
+/**
+ * Which rows a model page lists. A keyed nav entry with a `filter` lists only
+ * the rows matching it (`equals`); the model's plain entry lists the rest
+ * (`notIn`) once such an entry's recipe is added, so a row shows in one place.
+ */
+export interface RowScope {
+    field: string;
+    equals?: string;
+    notIn?: string[];
+}
+type ScopedEntry = Pick<RecipeNavTarget, 'key' | 'filter'> & {
+    model: {
+        id: string;
+    };
+};
+/**
+ * The scope of a page: `view` is the entry key in the path (none for the
+ * plain entry); `added` are the nav entries of the added recipes.
+ */
+export declare function pageScope(modelId: string, view: string | undefined, added: readonly ScopedEntry[]): RowScope | undefined;
+export declare function inScope(scope: RowScope | undefined, row: Record<string, unknown>): boolean;
+/** Values a row created from the page carries, so it stays in view. */
+export declare function scopePreset(scope: RowScope | undefined): Record<string, unknown>;
+export {};