@cosmicdrift/kumiko-framework 0.353.0 → 0.354.1

package/dist/engine/boot-validator/screens.js

@@ -12,7 +12,7 @@ import { isEncryptedAtRest } from "../config-helpers.js";
 import { parseRefTarget } from "../parse-ref-target.js";
 import { isKebabSegment, isValidQn, qualifyEntityName } from "../qualified-name.js";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops.js";
-import { isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../screen-helpers.js";
+import { explicitListScreenId, isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../screen-helpers.js";
 import { metricField } from "../types/index.js";
 import { LIST_ROW_META_COLUMN_NAMES } from "./entity-list-screens.js";
 import { isSelectOptionTone } from "./select-option-tone.js";
@@ -127,6 +127,11 @@ function validateRowActionNavigateParams(featureName, screenId, screenType, scre
             `the params extractor or retarget to an actionForm / secretMint / cross-entity ` +
             `entityEdit-create screen.`);
     }
+    const formTarget = target.screen;
+    if ((formTarget.type === "actionForm" || formTarget.type === "secretMint") &&
+        formTarget.submitPrefilled === true) {
+        validateDrawerPrefillKeys(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) rowAction "${action.id}"`, "navigate-target", action.screen ?? `entity "${action.entity}"`, formTarget, action.params);
+    }
 }
 // Shared by projectionDetail and entityEdit: a tab strip needs something to
 // label each tab with and a stable id per tab — the id anchors the ?tab=
@@ -353,9 +358,9 @@ function validateDrawerTargetAction(featureName, screenId, screenKind, actionLab
     // skip: no params extractor — nothing to check against the target's fields.
     if (action.params === undefined)
         return;
-    validateDrawerPrefillKeys(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}"`, action.screen, target, action.params);
+    validateDrawerPrefillKeys(`[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}"`, "drawer-target", action.screen, target, action.params);
 }
-function validateDrawerPrefillKeys(where, targetScreenId, target, params) {
+function validateDrawerPrefillKeys(where, targetLabel, targetScreenId, target, params) {
     const renderedFieldNames = new Set();
     for (const section of target.layout.sections) {
         if (!isFieldsEditSection(section))
@@ -365,7 +370,7 @@ function validateDrawerPrefillKeys(where, targetScreenId, target, params) {
     }
     for (const fieldName of rowFieldExtractorKeys(params)) {
         if (!Object.hasOwn(target.fields, fieldName)) {
-            throw new Error(`${where} params prefills "${fieldName}", which drawer-target "${targetScreenId}" does not declare as a ` +
+            throw new Error(`${where} params prefills "${fieldName}", which ${targetLabel} "${targetScreenId}" does not declare as a ` +
                 `field — the renderer would drop it and leave the form empty. Target fields: ` +
                 `${Object.keys(target.fields).sort().join(", ") || "(none)"}.`);
         }
@@ -374,11 +379,11 @@ function validateDrawerPrefillKeys(where, targetScreenId, target, params) {
             (("sensitive" in targetField && targetField.sensitive === true) ||
                 ("format" in targetField && targetField.format === "password"));
         if (isSensitiveOrPassword) {
-            throw new Error(`${where} params prefills "${fieldName}", which drawer-target "${targetScreenId}" marks as ` +
+            throw new Error(`${where} params prefills "${fieldName}", which ${targetLabel} "${targetScreenId}" marks as ` +
                 `sensitive or password — the renderer never prefills those fields and would leave the form empty.`);
         }
         if (!renderedFieldNames.has(fieldName)) {
-            throw new Error(`${where} params prefills "${fieldName}", which drawer-target "${targetScreenId}" does not render in ` +
+            throw new Error(`${where} params prefills "${fieldName}", which ${targetLabel} "${targetScreenId}" does not render in ` +
                 `its layout — the renderer only prefills fields the layout shows and would drop it.`);
         }
     }
@@ -519,9 +524,13 @@ function rejectWriteOnlyFormField(featureName, screenId, context, fieldName, fde
 // payload refs must name another field of the same form (the payload also feeds
 // optionsAvailabilityQuery). The QN existence check
 // lives in query-refs.ts with the other query refs.
+const CONDITIONAL_OPTIONS_ENTITY_ONLY = "conditionalOptions is only supported on entity select fields (enforced by the entity write path)";
 function validateFormSelectOptions(featureName, screenId, context, fieldName, fdef, siblingFieldNames) {
     if (fdef.type === "select") {
         const where = `[Feature ${featureName}] Screen "${screenId}" (${context}) select field "${fieldName}"`;
+        if (fdef.conditionalOptions !== undefined) {
+            throw new Error(`${where} declares conditionalOptions — ${CONDITIONAL_OPTIONS_ENTITY_ONLY}`);
+        }
         if (fdef.optionsQuery !== undefined) {
             if (fdef.optionsQuery.length === 0) {
                 throw new Error(`${where} has an empty optionsQuery`);
@@ -649,6 +658,17 @@ function validateRedirectTarget(feature, screenId, screenKind, redirect, allScre
             `has leading/trailing whitespace — it would never match a payload field.`);
     }
     validateScreenNavTarget(feature.name, screenId, screenKind, "redirect", redirectTarget, allScreenQns, feature.screens);
+    // idFrom only means something to a target that carries a record id; the
+    // renderer drops it silently otherwise. Cross-feature QN targets can't be
+    // typed from here and stay unchecked.
+    const sameFeatureTarget = feature.screens[redirectTarget];
+    if (typeof redirect !== "string" &&
+        sameFeatureTarget !== undefined &&
+        sameFeatureTarget.type !== "entityEdit" &&
+        sameFeatureTarget.type !== "projectionDetail") {
+        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screenKind}) redirect.idFrom is set but target screen ` +
+            `"${redirectTarget}" (${sameFeatureTarget.type}) carries no id — use the plain string form.`);
+    }
 }
 // redirect is only honored on record actions; on list/related-list row
 // actions it would be silently dropped, so the author would believe it works.
@@ -781,6 +801,20 @@ function getNavAreaIndex(featureMap) {
     navAreaIndexByFeatureMap.set(featureMap, index);
     return index;
 }
+// resolveNavParentScreen falls back to a heuristic when the explicit
+// listScreenId matches no screen, so a typo would silently get the guess.
+function validateExplicitListScreenExists(featureName, screenId, screen, screensByShortId) {
+    const listScreenId = explicitListScreenId(screen);
+    // skip: no explicit listScreenId, the nav heuristic applies and there is nothing to validate
+    if (listScreenId === undefined)
+        return;
+    const shortId = listScreenId.slice(listScreenId.lastIndexOf(":") + 1);
+    // skip: the explicit listScreenId resolves to a mounted screen
+    if (screensByShortId.has(shortId))
+        return;
+    throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screen.type}) listScreenId "${listScreenId}" ` +
+        `matches no mounted screen — fix the id or mount the list screen.`);
+}
 // Every screen must resolve nav via `nav`, `r.nav()`, a parent list, or
 // `dormant: true`. Skipped when the composed set has no nav entries at all.
 function validateScreenHasNavArea(feature, screenId, screen, featureMap) {
@@ -925,6 +959,22 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
         detailForScreens,
     };
     for (const [screenId, screen] of Object.entries(feature.screens)) {
+        validateExplicitListScreenExists(feature.name, screenId, screen, screensByShortId);
+        // Output of buildAppSchema, which overwrites it — an authored value would be a silent no-op.
+        if ((screen.type === "entityEdit" ||
+            screen.type === "actionForm" ||
+            screen.type === "secretMint") &&
+            screen.urlPrefillFields !== undefined) {
+            throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screen.type}) sets urlPrefillFields — ` +
+                `it is derived from navigate params by buildAppSchema; declare params on the navigating action instead.`);
+        }
+        if (screen.type !== "actionForm" &&
+            screen.type !== "secretMint" &&
+            "submitPrefilled" in screen &&
+            screen.submitPrefilled !== undefined) {
+            throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screen.type}) sets submitPrefilled — ` +
+                `only actionForm and secretMint screens support it. Remove it.`);
+        }
         validateScreenHasNavArea(feature, screenId, screen, featureMap);
         validateScreenVisibleWhen(feature, screenId, screen, allScreenQns, featureMap);
         if (screen.type === "custom") {
@@ -948,6 +998,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
             for (const col of screen.columns) {
                 const normalizedCol = normalizeListColumn(col);
                 validateColumnRendererForm(feature.name, screenId, normalizedCol);
+                rejectInertColumnSortable(feature.name, screenId, "projectionList", normalizedCol);
                 if (normalizedCol.refEntity !== undefined) {
                     assertRefTargetRegistered(`[Feature ${feature.name}] Screen "${screenId}" (projectionList)`, `column "${normalizedCol.field}" (refEntity)`, normalizedCol.refEntity, feature.name, featureMap);
                 }
@@ -1411,6 +1462,7 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     throw new Error(buildUnknownFieldMessage(feature.name, screenId, normalized.field, screen.entity, columnFieldNames));
                 }
                 validateColumnRendererForm(feature.name, screenId, normalized);
+                rejectInertColumnSortable(feature.name, screenId, "entityList", normalized);
                 if (normalized.refEntity !== undefined) {
                     assertRefTargetRegistered(`[Feature ${feature.name}] Screen "${screenId}" (entityList)`, `column "${normalized.field}" (refEntity)`, normalized.refEntity, feature.name, featureMap);
                 }
@@ -1811,6 +1863,12 @@ function validateDashboardChartDisplay(featureName, screenId, panel) {
         throw new Error(`${where} sets scrollable on chart "${panel.chart}" — only "stacked-area" supports it.`);
     }
     validateStackedAreaOnlyProps(where, panel);
+    validateStackedAreaEnumProp(where, "dateFormat", panel.dateFormat, ["day", "month"]);
+    validateStackedAreaEnumProp(where, "initialWindow", panel.initialWindow, [
+        "default-range",
+        "from-today",
+    ]);
+    validateStackedAreaEnumProp(where, "markerLegend", panel.markerLegend, ["list", "legend"]);
     const nonBooleanProp = ["brush", "legendTotals"].find((prop) => panel[prop] !== undefined && typeof panel[prop] !== "boolean");
     if (nonBooleanProp !== undefined) {
         throw new Error(`${where} has a non-boolean ${nonBooleanProp}.`);
@@ -1826,11 +1884,27 @@ function validateDashboardChartDisplay(featureName, screenId, panel) {
     if (panel.ranges !== undefined)
         validateDashboardChartRanges(`${where} ranges`, panel.ranges);
 }
+function validateStackedAreaEnumProp(where, prop, value, allowed) {
+    // skip: optional prop, nothing to validate when unset
+    if (value === undefined)
+        return;
+    if (!allowed.includes(value)) {
+        throw new Error(`${where}.${prop} "${String(value)}" must be one of ${allowed.join(", ")}.`);
+    }
+}
 function validateStackedAreaOnlyProps(where, panel) {
     // skip: stacked-area is the one chart kind that supports these props
     if (panel.chart === "stacked-area")
         return;
-    const stackedAreaOnly = ["markerKinds", "legendTotals", "ranges", "brush"].filter((prop) => panel[prop] !== undefined);
+    const stackedAreaOnly = [
+        "markerKinds",
+        "legendTotals",
+        "ranges",
+        "brush",
+        "dateFormat",
+        "initialWindow",
+        "markerLegend",
+    ].filter((prop) => panel[prop] !== undefined);
     if (stackedAreaOnly.length > 0) {
         throw new Error(`${where} sets ${stackedAreaOnly.join(", ")} on chart "${panel.chart}" — only "stacked-area" supports it.`);
     }
@@ -1851,6 +1925,9 @@ function validateDashboardChartMarkerKind(where, look) {
     if (look.color !== undefined && (typeof look.color !== "string" || look.color.trim() === "")) {
         throw new Error(`${where}.color must be a non-empty CSS color.`);
     }
+    if (look.label !== undefined && (typeof look.label !== "string" || look.label.trim() === "")) {
+        throw new Error(`${where}.label must be a non-empty i18n key.`);
+    }
 }
 function validateDashboardChartRanges(where, ranges) {
     if (ranges.options.length === 0) {
@@ -1949,6 +2026,20 @@ function validateDashboardFilterDefinition(featureName, screenId, filter) {
 // stimmt: wenn `react` als Object gesetzt ist, MUSS `__component` ein
 // nicht-leerer String sein. Ein client-seitig ausgelassener Key löst
 // nur eine Warnung aus, kein Boot-Fail.
+// Column-level sortable: true only enables relatedList headers. On entityList
+// the entity field's flag wins; on projectionList sortable comes from the
+// query schema and a column can only opt OUT with sortable: false.
+function rejectInertColumnSortable(featureName, screenId, screenType, column) {
+    const isInert = screenType === "entityList" ? column.sortable !== undefined : column.sortable === true;
+    // skip: the sortable flag is meaningful for this screen type
+    if (!isInert)
+        return;
+    const source = screenType === "entityList"
+        ? "set sortable: true on the entity field instead"
+        : "sorting is derived from the query's Zod schema; only sortable: false is honored";
+    throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) column "${column.field}" sets sortable — ` +
+        `it is ignored here; ${source}.`);
+}
 export function validateColumnRendererForm(featureName, screenId, column) {
     const renderer = column.renderer;
     // skip: nur die PlatformComponent-Form ({ react: { __component: "..." } })

package/dist/engine/boot-validator/transfer-graph.d.ts

@@ -1,3 +1,4 @@
+import { MAX_TRANSFER_DEPTH } from "../transfer-adjacency.js";
 import type { FeatureDefinition } from "../types/index.js";
-export declare const MAX_TRANSFER_DEPTH = 5;
+export { MAX_TRANSFER_DEPTH };
 export declare function validateTransferGraph(feature: FeatureDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>): void;

package/dist/engine/boot-validator/transfer-graph.js

@@ -1,4 +1,5 @@
 import { parseRefTargetEntityName } from "../parse-ref-target.js";
+import { findOverDeepTransferChain, MAX_TRANSFER_DEPTH, resolveTransferAdjacency, } from "../transfer-adjacency.js";
 // --- Transfer-graph boot validation (fw#3088) ---
 //
 // tenant-handover walks an entity graph across the tenant boundary along two
@@ -9,16 +10,7 @@ import { parseRefTargetEntityName } from "../parse-ref-target.js";
 //
 // Scoped to entities declaring `transferable: true`, so a consumer that has
 // one of these shapes but never hands that entity over is unaffected.
-// The single definition of the limit. It lives here rather than next to the
-// resolver in bundled-features because the dependency only runs that way:
-// bundled-features imports from the framework, never the reverse.
-//
-// Guards against a schema whose reference edges span more levels than anyone
-// intended — a runaway graph would move rows an operator never associated with
-// the handover. Deliberately a constant and not per-feature config: the limit
-// is a safety net, and a configurable one gets raised by whoever trips it
-// instead of prompting them to reconsider their graph.
-export const MAX_TRANSFER_DEPTH = 5;
+export { MAX_TRANSFER_DEPTH };
 function allEntities(featureMap) {
     const out = [];
     for (const feature of featureMap.values()) {
@@ -28,17 +20,6 @@ function allEntities(featureMap) {
     }
     return out;
 }
-function referenceTargets(entity) {
-    const targets = [];
-    for (const field of Object.values(entity.fields)) {
-        if (field.type !== "reference")
-            continue;
-        if (field.multiple === true)
-            continue;
-        targets.push(parseRefTargetEntityName(field.entity));
-    }
-    return targets;
-}
 // A `multiple` reference stores a jsonb array of ids, which the handover's
 // `= ANY($ids)` column match cannot address. Declaring one towards a transferable
 // entity would mean its rows never move with their host. A target outside the
@@ -52,6 +33,8 @@ function validateNoMultipleReferenceEdge(entry, featureName, transferable) {
     for (const [fieldName, field] of Object.entries(entry.entity.fields)) {
         if (field.type !== "reference" || field.multiple !== true)
             continue;
+        if (field.handover === "stay")
+            continue;
         if (!transferable.has(parseRefTargetEntityName(field.entity)))
             continue;
         throw new Error(`[Kumiko TransferGraph] entity "${entry.name}" declares transferable: true and a ` +
@@ -62,31 +45,6 @@ function validateNoMultipleReferenceEdge(entry, featureName, transferable) {
             `from "${entry.name}".`);
     }
 }
-// Depth is measured over reference edges between transferable entities, the
-// only chain that nests (parentRef is one level by construction — see
-// engine/boot-validator/parent-ref.ts).
-//
-// `onPath` counts NODES, the limit counts EDGES: a chain of exactly
-// MAX_TRANSFER_DEPTH edges holds MAX_TRANSFER_DEPTH + 1 entities, and the
-// mover runs MAX_TRANSFER_DEPTH rounds of one hop each, so it still walks that
-// chain whole. Rejecting it here would make a schema the mover handles
-// correctly refuse to boot.
-function longestTransferableChain(startName, bySource, onPath) {
-    if (onPath.length > MAX_TRANSFER_DEPTH + 1)
-        return onPath;
-    for (const target of bySource.get(startName) ?? []) {
-        // skip: a cycle revisits a type already on this path, and schema depth
-        // cannot measure how far it actually runs — that depends on the rows, not
-        // the declaration. The mover carries this one instead, failing with
-        // `transfer_graph_too_deep` when its rounds run out (#3131).
-        if (onPath.includes(target))
-            continue;
-        const deeper = longestTransferableChain(target, bySource, [...onPath, target]);
-        if (deeper !== undefined)
-            return deeper;
-    }
-    return undefined;
-}
 export function validateTransferGraph(feature, featureMap) {
     const transferable = new Set(allEntities(featureMap)
         .filter((e) => e.entity.transferable === true)
@@ -94,30 +52,17 @@ export function validateTransferGraph(feature, featureMap) {
     for (const [name, entity] of Object.entries(feature.entities ?? {})) {
         validateNoMultipleReferenceEdge({ name, entity }, feature.name, transferable);
     }
-    // Edges point child -> parent in the schema; the graph walks parent -> child,
-    // so the lookup is inverted here.
-    const childrenByParent = new Map();
-    for (const { name, entity } of allEntities(featureMap)) {
-        if (!transferable.has(name))
-            continue;
-        for (const target of referenceTargets(entity)) {
-            if (!transferable.has(target))
-                continue;
-            const children = childrenByParent.get(target) ?? [];
-            children.push(name);
-            childrenByParent.set(target, children);
-        }
-    }
+    const adjacency = resolveTransferAdjacency(new Map(allEntities(featureMap).map(({ name, entity }) => [name, entity])));
     for (const [name, entity] of Object.entries(feature.entities ?? {})) {
         if (entity.transferable !== true)
             continue;
-        const tooDeep = longestTransferableChain(name, childrenByParent, [name]);
+        const tooDeep = findOverDeepTransferChain(adjacency, [name]);
         if (tooDeep !== undefined) {
             throw new Error(`[Kumiko TransferGraph] the transfer graph rooted at entity "${name}" is deeper than ` +
                 `the ${MAX_TRANSFER_DEPTH}-level limit (feature: "${feature.name}"): ` +
                 `${tooDeep.join(" -> ")}. Beyond that depth tenant-handover would move fewer rows ` +
-                `than the declaration implies. Fix: flatten the chain, or drop transferable from an ` +
-                `entity in it that should not move with its host.`);
+                `than the declaration implies. Fix: flatten the chain, or mark a reference field on ` +
+                `an entity in it that should not move with its host \`handover: "stay"\`.`);
         }
     }
 }

package/dist/engine/boot-validator/url-prefill-fields.d.ts

@@ -1,2 +1,3 @@
 import type { FeatureDefinition } from "../types/index.js";
 export declare function collectUrlPrefillFieldsByScreenQn(features: readonly FeatureDefinition[]): Map<string, Set<string>>;
+export declare function validateSubmitPrefilledHiddenFields(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/url-prefill-fields.js

@@ -1,4 +1,5 @@
 import { qualifyEntityName } from "../qualified-name.js";
+import { isFieldsEditSection, normalizeEditField, sectionFieldSpecs } from "../screen-helpers.js";
 import { collectScreensByShortId, readsNavigateParamsAsFormPrefill, rowFieldExtractorKeys, } from "./screens.js";
 function isNavigateKind(action) {
     return action.kind === undefined || action.kind === "navigate";
@@ -123,3 +124,37 @@ function resolveTarget(source, screensByShortId, detailForByEntity) {
     const match = screensByShortId.get(source.screen)?.[0];
     return match === undefined ? undefined : { ...match, shortId: source.screen };
 }
+// submitPrefilled lets an unchanged form submit, so a required field the layout
+// hides must be seeded by a navigate param — nothing else can ever fill it.
+export function validateSubmitPrefilledHiddenFields(features) {
+    const prefillByScreenQn = collectUrlPrefillFieldsByScreenQn(features);
+    for (const feature of features) {
+        for (const [screenId, screen] of Object.entries(feature.screens)) {
+            if (screen.type !== "actionForm" && screen.type !== "secretMint")
+                continue;
+            if (screen.submitPrefilled !== true)
+                continue;
+            const seeded = prefillByScreenQn.get(qualifyEntityName(feature.name, "screen", screenId));
+            for (const section of screen.layout.sections) {
+                if (!isFieldsEditSection(section))
+                    continue;
+                for (const rawSpec of sectionFieldSpecs(section)) {
+                    const spec = normalizeEditField(rawSpec);
+                    if (spec.visible !== false)
+                        continue;
+                    const fieldDef = screen.fields[spec.field];
+                    if (fieldDef === undefined || !("required" in fieldDef) || fieldDef.required !== true) {
+                        continue;
+                    }
+                    if (seeded?.has(spec.field) === true)
+                        continue;
+                    throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screen.type}) sets submitPrefilled but ` +
+                        `hides required field "${spec.field}" (visible: false) and no navigate action passes it in ` +
+                        `params — the field could never get a value and the form could never submit. Add ` +
+                        `"${spec.field}" to the params of a navigate action targeting this screen, make the field ` +
+                        `visible, or drop required.`);
+                }
+            }
+        }
+    }
+}

package/dist/engine/build-app-schema.js

@@ -459,6 +459,9 @@ function projectField(fieldDef) {
     // Select: tier/tenant availability of the static options, loaded by the renderer.
     if (typeof def["optionsAvailabilityQuery"] === "string")
         out["optionsAvailabilityQuery"] = def["optionsAvailabilityQuery"];
+    // Select: options only offered while a sibling-field condition holds; the renderer filters, the write path enforces.
+    if (Array.isArray(def["conditionalOptions"]))
+        out["conditionalOptions"] = def["conditionalOptions"];
     if (typeof def["multiple"] === "boolean")
         out["multiple"] = def["multiple"];
     // MultiSelect: display picks checkboxes vs. combobox in the renderer,

package/dist/engine/changeset-changes.d.ts

@@ -6,6 +6,7 @@ export type PendingChange = {
     readonly detail?: string;
     readonly migration?: string;
     readonly codemod?: string;
+    readonly manualAfterCodemod?: boolean;
     readonly source: string;
 };
 /** Parse structured upgrade metadata embedded in a Changeset body. */

package/dist/engine/changeset-changes.js

@@ -1,7 +1,7 @@
 import { validateChangelog } from "./feature-changelog.js";
 const BLOCK_RE = /<!--\s*kumiko-changes\s*\n([\s\S]*?)\n\s*-->/g;
 const TYPE_VALUES = new Set(["breaking", "improvement", "fix"]);
-const KEY_RE = /^(feature|type|title|detail|migration|codemod):(?:\s(.*))?$/;
+const KEY_RE = /^(feature|type|title|detail|migration|codemod|manualAfterCodemod):(?:\s(.*))?$/;
 function requiredField(fields, field, source) {
     const value = fields.get(field)?.trim();
     if (!value)
@@ -70,6 +70,53 @@ function assertBlockNotClosedEarly(markdown, match, source) {
         throw new Error(`${source}: kumiko-changes block closed early by a line starting with "-->"; field values must not contain such a line`);
     }
 }
+function resolveTitleAndDetail(fields, prose, source) {
+    const explicitTitle = fields.get("title")?.trim();
+    const title = explicitTitle || prose[0];
+    if (!title)
+        throw new Error(`${source}: kumiko-changes title is required`);
+    // The first prose line is the title's source only when no title was given or
+    // the explicit one restates it; otherwise it is genuine detail.
+    const firstLineIsTitle = !explicitTitle || sameTitle(explicitTitle, prose[0]);
+    const detail = fields.get("detail")?.trim() ||
+        prose
+            .slice(firstLineIsTitle ? 1 : 0)
+            .join("\n")
+            .trim();
+    return { title, detail };
+}
+function parseManualAfterCodemod(fields, source) {
+    const raw = fields.get("manualAfterCodemod")?.trim();
+    if (raw !== undefined && raw !== "true" && raw !== "false") {
+        throw new Error(`${source}: kumiko-changes manualAfterCodemod must be true or false`);
+    }
+    return raw === "true";
+}
+function buildChange(fields, prose, source) {
+    const feature = requiredField(fields, "feature", source);
+    const rawType = requiredField(fields, "type", source);
+    if (!TYPE_VALUES.has(rawType)) {
+        throw new Error(`${source}: kumiko-changes type must be breaking, improvement, or fix`);
+    }
+    const { title, detail } = resolveTitleAndDetail(fields, prose, source);
+    const migration = fields.get("migration")?.trim();
+    const codemod = fields.get("codemod")?.trim();
+    const manualAfterCodemod = parseManualAfterCodemod(fields, source);
+    const change = {
+        feature,
+        type: rawType,
+        title,
+        ...(detail ? { detail } : {}),
+        ...(migration ? { migration } : {}),
+        ...(codemod ? { codemod } : {}),
+        ...(manualAfterCodemod ? { manualAfterCodemod: true } : {}),
+        source,
+    };
+    const validation = validateChangelog({ version: "0.0.0", ...change });
+    if (validation.length > 0)
+        throw new Error(`${source}: ${validation.join("; ")}`);
+    return change;
+}
 /** Parse structured upgrade metadata embedded in a Changeset body. */
 export function parseChangesetChanges(markdown, source) {
     const changes = [];
@@ -85,38 +132,7 @@ export function parseChangesetChanges(markdown, source) {
         assertBlockNotClosedEarly(markdown, match, source);
         if (!block)
             throw new Error(`${source}: empty kumiko-changes block`);
-        const fields = parseBlock(block, source);
-        const feature = requiredField(fields, "feature", source);
-        const rawType = requiredField(fields, "type", source);
-        if (!TYPE_VALUES.has(rawType)) {
-            throw new Error(`${source}: kumiko-changes type must be breaking, improvement, or fix`);
-        }
-        const explicitTitle = fields.get("title")?.trim();
-        const title = explicitTitle || prose[0];
-        if (!title)
-            throw new Error(`${source}: kumiko-changes title is required`);
-        // The first prose line is the title's source only when no title was given or
-        // the explicit one restates it; otherwise it is genuine detail.
-        const firstLineIsTitle = !explicitTitle || sameTitle(explicitTitle, prose[0]);
-        const detail = fields.get("detail")?.trim() ||
-            prose
-                .slice(firstLineIsTitle ? 1 : 0)
-                .join("\n")
-                .trim();
-        const migration = fields.get("migration")?.trim();
-        const codemod = fields.get("codemod")?.trim();
-        const change = {
-            feature,
-            type: rawType,
-            title,
-            ...(detail ? { detail } : {}),
-            ...(migration ? { migration } : {}),
-            ...(codemod ? { codemod } : {}),
-            source,
-        };
-        const validation = validateChangelog({ version: "0.0.0", ...change });
-        if (validation.length > 0)
-            throw new Error(`${source}: ${validation.join("; ")}`);
+        const change = buildChange(parseBlock(block, source), prose, source);
         changes.push(change);
         match = BLOCK_RE.exec(markdown);
     }

package/dist/engine/define-feature.js

@@ -22,7 +22,18 @@ import { unwrapArrayForm } from "./object-form.js";
 function resolveFeatureNamesArgs(args) {
     return unwrapArrayForm(args, "features");
 }
+// dedupe-features compares options with Object.is per key, so a nested object
+// would make two structurally identical mounts look different and fail the boot
+// with an unobvious "mounted twice with different options".
+function assertDedupeOptionsComparable(featureName, options) {
+    for (const [key, value] of Object.entries(options ?? {})) {
+        if (typeof value === "object" && value !== null) {
+            throw new Error(`[Feature ${featureName}] dedupeOptions.${key} must be a primitive or a stable function reference; dedupeOptions are compared shallowly, so a nested object never matches a second mount`);
+        }
+    }
+}
 export function defineFeature(name, setup, settings) {
+    assertDedupeOptionsComparable(name, settings?.dedupeOptions);
     const state = createInitialFeatureBuilderState();
     const registrar = {
         systemScope() {

package/dist/engine/entity-handlers.d.ts

@@ -4,8 +4,6 @@ import { type EntityTable } from "../db/table-builder.js";
 import type { EntityCrudRegistrar, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions } from "./types/entity-handlers.js";
 import type { AccessRule, EntityDefinition, EscapeHatchDeclaration, QueryHandlerDef, WriteHandlerDef } from "./types/index.js";
 export type { EntityCrudHandlerDefaults, EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "./types/entity-handlers.js";
-export declare function isDeprecatedCrossTenantHandler(handler: object): boolean;
-export declare const DEPRECATED_CROSS_TENANT_SIGNAL = "deprecation:entity-handler-cross-tenant";
 export declare const MAX_LIST_LIMIT = 200;
 export declare const entityListSchema: z.ZodObject<{
     cursor: z.ZodOptional<z.ZodString>;
@@ -60,7 +58,9 @@ export declare function createEntityExecutor(entityName: string, entity: EntityD
 };
 export declare function defineProjectionQueryHandler(name: string, projectionQualifiedName: string, options: {
     access: AccessRule;
-    unsafeAllTenants?: boolean;
+    unsafeAllTenants?: boolean | {
+        readonly reason: string;
+    };
     escapeHatch?: EscapeHatchDeclaration;
 }): QueryHandlerDef;
 /** Register standard entity CRUD handlers in one call. Access stays explicit — no openToAll default. */