@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

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

@@ -1,8 +1,8 @@
 import { isListQueryWithoutSearchableFields, resolveEntityBehindListQuery, } from "../entity-list-searchability.js";
 import { QnTypes, qualifyEntityName } from "../qualified-name.js";
 import { isEditLayoutScreen } from "../screen-helpers.js";
-import { relatedListGroupHeaderLabel, relatedListGroupKey, } from "../types/index.js";
 import { SEARCHABLE_FALSE_WHITELIST } from "./entity-list-screens.js";
+import { validateListTableAggregateQuery } from "./list-table-aggregate-query.js";
 import { findEntity } from "./parent-ref.js";
 import { getZodObjectShape } from "./zod-shape.js";
 // Sibling to entity-list-screens.ts rather than an extension of it:
@@ -66,6 +66,7 @@ function validateOneProjectionListScreen(feature, screen, queryHandlers, feature
     }
     validateProjectionListFilterSchemaAcceptance(prefix, screen, schema);
     validateProjectionListFacetsSchemaAcceptance(prefix, screen, schema);
+    validateListTableAggregateQuery({ prefix, ...screen, handler, featureMap });
 }
 // filter sends `payload.filter` — same 422 footgun as facets below
 // if the handler's schema doesn't accept it.
@@ -190,17 +191,6 @@ function validateRelatedListParentFilter(prefix, section, schema, handler, featu
             `entity behind query "${section.query}". Known fields: ${Object.keys(entity.fields).sort().join(", ")}.`);
     }
 }
-// A collapsed group without a header has no toggle, so its rows could never be opened.
-function validateRelatedListGroupBy(prefix, section) {
-    const groupBy = section.groupBy;
-    const collapsedKey = groupBy?.collapsedWhen === undefined ? undefined : relatedListGroupKey(groupBy.collapsedWhen);
-    if (groupBy !== undefined &&
-        collapsedKey !== undefined &&
-        relatedListGroupHeaderLabel(groupBy, collapsedKey) === undefined) {
-        throw new Error(`${prefix}: groupBy.collapsedWhen "${collapsedKey}" names a group without a header; ` +
-            `set groupBy.label or groupBy.labels["${collapsedKey}"], or drop collapsedWhen.`);
-    }
-}
 // relatedList sections declare search/facets the same way a projectionList
 // screen does, and hit the same 422 footgun: definePagedQueryHandler doesn't
 // auto-merge params into the handler's own Zod schema, so an
@@ -217,7 +207,7 @@ export function validateRelatedListSectionQueries(features) {
         validateRelatedListSearchable(prefix, section, schema);
         validateRelatedListFacets(prefix, section, schema);
         validateRelatedListParentFilter(prefix, section, schema, handler, featureMap);
-        validateRelatedListGroupBy(prefix, section);
+        validateListTableAggregateQuery({ prefix, ...section, handler, featureMap });
     };
     for (const feature of features) {
         for (const screen of Object.values(feature.screens)) {

package/dist/engine/boot-validator/query-refs.d.ts

@@ -1,3 +1,4 @@
-import type { FeatureDefinition, QueryHandlerDef } from "../types/index.ts";
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
+import type { FeatureDefinition } from "../types/index.ts";
 export declare function checkQueryRef(queryHandlers: ReadonlyMap<string, QueryHandlerDef>, query: string, buildPrefix: () => string): void;
 export declare function validateQueryRefs(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/related-list-table-rules.d.ts

@@ -0,0 +1,4 @@
+/** Grouping rules of a relatedList section or entityList.expandableRow, before the shared table checks. */
+export declare function validateRelatedListGroupingRules(prefix: string, section: {
+    readonly table?: unknown;
+}, isExpandableRow: boolean): void;

package/dist/engine/boot-validator/related-list-table-rules.js

@@ -0,0 +1,42 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+const EXPANDABLE_ROW_TABLE_KEYS = new Set(["grouping"]);
+const EXPANDABLE_ROW_REJECTED_GROUPING_KEYS = ["userChoice", "fields"];
+// `groupBy` grouped the loaded page on the client; it is gone, and a screen
+// still carrying it fails at boot instead of silently losing its groups.
+function rejectRemovedGroupBy(prefix, section) {
+    if (Object.hasOwn(section, "groupBy")) {
+        throw new Error(`${prefix} uses groupBy, which was removed. Use table.grouping: { field, label?, labels?, collapsedWhen? }; ` +
+            `groups and counts come from the server, so the bound query must accept aggregate.`);
+    }
+}
+function rejectExpandableRowTableOptions(prefix, table) {
+    if (isPlainObject(table)) {
+        rejectUnsupportedTableKeys(prefix, table);
+        rejectGroupingChoice(prefix, table["grouping"]);
+    }
+}
+function rejectUnsupportedTableKeys(prefix, table) {
+    const unsupported = Object.keys(table).filter((key) => !EXPANDABLE_ROW_TABLE_KEYS.has(key));
+    if (unsupported.length > 0) {
+        throw new Error(`${prefix} supports only table.grouping, not table.${unsupported.join(", table.")}. ` +
+            `Put the other table options on the entityList screen itself.`);
+    }
+}
+function rejectGroupingChoice(prefix, grouping) {
+    const choiceKey = isPlainObject(grouping)
+        ? EXPANDABLE_ROW_REJECTED_GROUPING_KEYS.find((key) => Object.hasOwn(grouping, key))
+        : undefined;
+    if (choiceKey !== undefined) {
+        throw new Error(`${prefix} does not support table.grouping.${choiceKey}: an expanded row has no view menu. ` +
+            `Set a fixed table.grouping.field.`);
+    }
+}
+/** Grouping rules of a relatedList section or entityList.expandableRow, before the shared table checks. */
+export function validateRelatedListGroupingRules(prefix, section, isExpandableRow) {
+    rejectRemovedGroupBy(prefix, section);
+    if (isExpandableRow && Object.hasOwn(section, "bulkActions")) {
+        throw new Error(`${prefix} does not support bulkActions. Put bulkActions on the entityList screen itself.`);
+    }
+    if (isExpandableRow)
+        rejectExpandableRowTableOptions(prefix, section.table);
+}

package/dist/engine/boot-validator/screens-forms.d.ts

@@ -1,5 +1,6 @@
+import type { EntityDefinition, FieldDefinition } from "@cosmicdrift/kumiko-types/fields";
 import type { FieldsOrGroupsSection } from "../screen-helpers.ts";
-import type { EntityDefinition, FeatureDefinition, FieldDefinition } from "../types/index.ts";
+import type { FeatureDefinition } from "../types/index.ts";
 import type { ActionFormScreenDefinition, ConfigEditScreenDefinition, EditFieldSpec, EditLayout, SecretMintScreenDefinition } from "../types/screen.ts";
 import type { NavigateTargetLookups } from "./screens-actions.ts";
 export declare function validateEditFieldExtras(featureName: string, screenId: string, entityDef: EntityDefinition, fieldSpec: Exclude<EditFieldSpec, string>): void;

package/dist/engine/boot-validator/screens-kind-entity-list.js

@@ -3,7 +3,10 @@ import { rowMetaFieldNames } from "../../db/table-builder.js";
 import { qualifyEntityName } from "../qualified-name.js";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops.js";
 import { normalizeListColumn } from "../screen-helpers.js";
+import { validateEntityListAggregateOptions } from "./entity-list-aggregate-options.js";
 import { LIST_ROW_META_COLUMN_NAMES } from "./entity-list-screens.js";
+import { validateListBulkActions } from "./list-bulk-actions.js";
+import { validateListTableOptions } from "./list-table-options.js";
 import { assertWriteHandlerRegistered, rejectRedirectOnListRowAction, resolveRowActionNavigateTarget, validateActionFieldRefs, validateAtMostOneRowClick, validateDrawerTargetAction, validateRowActionNavigateParams, } from "./screens-actions.js";
 import { buildUnknownFieldMessage, listActionContext, rejectEmptyColumns, rejectNonArrayInFilter, resolveScreenEntity, validateListColumnRendering, } from "./screens-kind-shared.js";
 import { validateRelatedListSection, validateRowActionTarget } from "./screens-lists.js";
@@ -201,6 +204,9 @@ export function validateEntityListScreen(ctx, screenId, screen) {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) has pageSize=${screen.pageSize} — ` +
             `must be a positive integer.`);
     }
+    const where = `[Feature ${featureName}] Screen "${screenId}" (entityList)`;
+    validateListTableOptions(where, screen.table, screen.columns, true);
+    validateEntityListAggregateOptions(where, screen, fields.entityDef);
     if (screen.defaultSort !== undefined) {
         validateEntityListDefaultSort(featureName, screenId, screen.defaultSort, fields);
     }
@@ -219,6 +225,7 @@ export function validateEntityListScreen(ctx, screenId, screen) {
         }
         validateAtMostOneRowClick(featureName, screenId, "entityList", screen.rowActions);
     }
+    validateListBulkActions(`[Feature ${featureName}] Screen "${screenId}" (entityList)`, screen.bulkActions, screen.rowActions);
     for (const action of screen.toolbarActions ?? []) {
         validateEntityListToolbarAction(ctx, screenId, fields, action);
     }

package/dist/engine/boot-validator/screens-kind-projection-list.js

@@ -1,4 +1,6 @@
 import { normalizeListColumn } from "../screen-helpers.js";
+import { validateListBulkActions } from "./list-bulk-actions.js";
+import { validateListTableOptions } from "./list-table-options.js";
 import { assertWriteHandlerRegistered, resolveRowActionNavigateTarget, validateAtMostOneRowClick, validateDrawerTargetAction, } from "./screens-actions.js";
 import { listActionContext, rejectEmptyColumns, rejectMissingQuery, rejectNonArrayInFilter, validateListColumnRendering, } from "./screens-kind-shared.js";
 import { validateListActionTargets, validateListFacets } from "./screens-lists.js";
@@ -34,6 +36,7 @@ export function validateProjectionListScreen(ctx, screenId, screen) {
     for (const col of screen.columns) {
         validateListColumnRendering(ctx, screenId, "projectionList", normalizeListColumn(col));
     }
+    validateListTableOptions(`[Feature ${featureName}] Screen "${screenId}" (projectionList)`, screen.table, screen.columns, true);
     // Screen filter: field existence can't be checked without an entity (columns
     // aren't a complete field inventory of the underlying query), so only the
     // structure is pinned: "in" requires an array.
@@ -46,6 +49,7 @@ export function validateProjectionListScreen(ctx, screenId, screen) {
     if (screen.rowActions !== undefined) {
         validateProjectionListRowActions(ctx, screenId, screen.rowActions);
     }
+    validateListBulkActions(`[Feature ${featureName}] Screen "${screenId}" (projectionList)`, screen.bulkActions, screen.rowActions);
     if (screen.toolbarActions !== undefined) {
         validateProjectionListToolbarActions(ctx, screenId, screen.toolbarActions);
     }

package/dist/engine/boot-validator/screens-kind-shared.d.ts

@@ -1,5 +1,7 @@
+import type { ConfigKeyDefinition } from "@cosmicdrift/kumiko-types/config";
+import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
 import { type normalizeListColumn } from "../screen-helpers.ts";
-import type { ConfigKeyDefinition, EntityDefinition, FeatureDefinition } from "../types/index.ts";
+import type { FeatureDefinition } from "../types/index.ts";
 import type { EditExtensionSection, EditFieldsSection, EditSectionSpec, RowAction } from "../types/screen.ts";
 import type { NavigateSourceScreenType, NavigateTargetLookups } from "./screens-actions.ts";
 import { type resolveRowActionNavigateTarget } from "./screens-actions.ts";

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

@@ -2,6 +2,9 @@ import { REFERENCE_LOOKUP_SOURCES } from "../../ui-types/list-row-meta.js";
 import { parseRefTarget } from "../parse-ref-target.js";
 import { qualifyEntityName } from "../qualified-name.js";
 import { explicitListScreenId, normalizeListColumn, resolveNavParentScreen, } from "../screen-helpers.js";
+import { validateListBulkActions } from "./list-bulk-actions.js";
+import { validateListTableOptions } from "./list-table-options.js";
+import { validateRelatedListGroupingRules } from "./related-list-table-rules.js";
 import { assertWriteHandlerRegistered, isRowClickAction, rejectRedirectOnListRowAction, resolveRowActionNavigateTarget, validateClientActionName, validateDrawerTargetAction, validateRowActionNavigateParams, } from "./screens-actions.js";
 // validateScreenHasNavArea runs once per screen; the index is built once per
 // featureMap (immutable during boot) instead of re-scanning every feature each call.
@@ -70,6 +73,14 @@ export function validateScreenHasNavArea(feature, screenId, screen, featureMap)
 }
 // Shared by projectionDetail relatedList sections and entityList.expandableRow:
 // both render a relatedList whose rows come from an arbitrary query.
+function validateRelatedListTableAndBulk(args) {
+    const { featureName, where, section } = args;
+    validateRelatedListGroupingRules(`[Feature ${featureName}] ${where}`, section, args.screenType === "entityList expandableRow");
+    validateListTableOptions(`[Feature ${featureName}] ${where}`, section.table, section.columns);
+    if (section.rowActions !== undefined)
+        validateRelatedListRowActions(args, section.rowActions);
+    validateListBulkActions(`[Feature ${featureName}] ${where}`, section.bulkActions, section.rowActions);
+}
 export function validateRelatedListSection(args) {
     const { featureName, featureMap, where, section } = args;
     if (!section.query || typeof section.query !== "string") {
@@ -93,8 +104,7 @@ export function validateRelatedListSection(args) {
                 `detailFor: "${targetEntity}". Add detailFor: "${targetEntity}" to the screen that shows it.`);
         }
     }
-    if (section.rowActions !== undefined)
-        validateRelatedListRowActions(args, section.rowActions);
+    validateRelatedListTableAndBulk(args);
     if (section.defaultSort !== undefined)
         validateRelatedListDefaultSort(args, section.defaultSort);
     if (section.facets !== undefined) {

package/dist/engine/boot-validator/screens.d.ts

@@ -1,4 +1,5 @@
-import type { ConfigKeyDefinition, FeatureDefinition } from "../types/index.ts";
+import type { ConfigKeyDefinition } from "@cosmicdrift/kumiko-types/config";
+import type { FeatureDefinition } from "../types/index.ts";
 import type { ScreenDefinition } from "../types/screen.ts";
 export { readsNavigateParamsAsFormPrefill, resolveScreenTargetQn, rowFieldExtractorKeys, validateActionFieldRefs, validateActionHasIcon, validateDrawerPrefillKeys, validateScreenShortIdCollisions, } from "./screens-actions.ts";
 export { validateDashboardCustomPanel, validateDashboardScreenPanel } from "./screens-dashboard.ts";

package/dist/engine/boot-validator/workspaces.d.ts

@@ -1,4 +1,6 @@
-import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types/index.ts";
+import type { NavDefinition } from "@cosmicdrift/kumiko-types/nav";
+import type { WorkspaceDefinition } from "@cosmicdrift/kumiko-types/workspace";
+import type { FeatureDefinition } from "../types/index.ts";
 export declare function collectWorkspaceQns(features: readonly FeatureDefinition[]): Map<string, WorkspaceDefinition & {
     readonly featureName: string;
 }>;

package/dist/engine/bridge-stub.d.ts

@@ -1,4 +1,7 @@
-import type { HandlerContext, SessionUser } from "./types/index.ts";
+import type { ContextServices, HandlerContext, HandlerDispatch, HandlerObservability, SessionUser } from "./types/index.ts";
 export declare function bridgeStub(opts?: {
     readonly user?: SessionUser;
-}): Pick<HandlerContext, "query" | "queryAs" | "write" | "writeAs" | "appendEvent" | "unsafeAppendEvent" | "tryAppendEvent" | "fetchForWriting" | "loadAggregate" | "archiveStream" | "restoreStream" | "isStreamArchived" | "snapshotAggregate" | "loadAggregateWithSnapshot" | "queryProjection" | "resolveAuthClaims" | "resolveActiveMembership" | "queryAsMember" | "hasFeature" | "metrics" | "metricsFor" | "tracer" | "tz" | "locale" | "user">;
+    readonly log?: HandlerObservability["log"];
+    readonly dispatch?: Partial<HandlerDispatch>;
+    readonly services?: Partial<ContextServices>;
+}): Pick<HandlerContext, "dispatch" | "events" | "auth" | "obs" | "hasFeature" | "tz" | "locale" | "user" | "services" | "lifecycle" | "tenants">;

package/dist/engine/bridge-stub.js

@@ -1,5 +1,7 @@
 import { DEFAULT_LOCALE } from "../i18n/request-locale.js";
-import { createNoopMetricsHandle, getFallbackTracer } from "../observability/index.js";
+import { createFallbackFullLogger } from "../logging/utils.js";
+import { getFallbackTracer } from "../observability/fallback.js";
+import { createNoopMetricsHandle } from "../observability/index.js";
 import { createTzContext } from "../time/index.js";
 import { createAnonymousUser } from "./system-user.js";
 // Test/service helper: cross-feature bridge methods that throw on use.
@@ -7,7 +9,7 @@ import { createAnonymousUser } from "./system-user.js";
 // Production code always receives a full HandlerContext from the Dispatcher's
 // buildHandlerContext (with real query/write closures). Some internal services
 // and tests construct a mini-context manually (typically just `{ db, registry }`)
-// to invoke a single handler. Those call sites don't use ctx.query/write —
+// to invoke a single handler. Those call sites don't use ctx.dispatch.query/write —
 // the stubs make the TypeScript shape match while still failing loudly if
 // anything downstream accidentally reaches for them.
 //
@@ -15,7 +17,7 @@ import { createAnonymousUser } from "./system-user.js";
 const notAvailable = (what) => async (..._args) => {
     throw new Error(`ctx.${what} not available in this context — use the dispatcher, not a stubbed handler context`);
 };
-// Noop observability — hand back the shared fallback tracer so ctx.tracer has
+// Noop observability — hand back the shared fallback tracer so ctx.obs.tracer has
 // a valid Tracer shape. No allocations per call.
 const noopTracer = getFallbackTracer();
 export function bridgeStub(opts) {
@@ -27,35 +29,48 @@ export function bridgeStub(opts) {
     const stubUser = opts?.user ?? createAnonymousUser("00000000-0000-0000-0000-000000000000");
     return {
         user: stubUser,
-        query: notAvailable("query"),
-        queryAs: notAvailable("queryAs"),
-        write: notAvailable("write"),
-        writeAs: notAvailable("writeAs"),
-        appendEvent: notAvailable("appendEvent"),
-        unsafeAppendEvent: notAvailable("unsafeAppendEvent"),
-        tryAppendEvent: notAvailable("tryAppendEvent"),
-        fetchForWriting: notAvailable("fetchForWriting"),
-        loadAggregate: notAvailable("loadAggregate"),
-        archiveStream: notAvailable("archiveStream"),
-        restoreStream: notAvailable("restoreStream"),
-        isStreamArchived: notAvailable("isStreamArchived"),
-        snapshotAggregate: notAvailable("snapshotAggregate"),
-        loadAggregateWithSnapshot: notAvailable("loadAggregateWithSnapshot"),
-        queryProjection: notAvailable("queryProjection"),
-        resolveAuthClaims: notAvailable("resolveAuthClaims"),
-        resolveActiveMembership: notAvailable("resolveActiveMembership"),
-        queryAsMember: notAvailable("queryAsMember"),
+        dispatch: {
+            query: notAvailable("dispatch.query"),
+            queryAs: notAvailable("dispatch.queryAs"),
+            write: notAvailable("dispatch.write"),
+            writeAs: notAvailable("dispatch.writeAs"),
+            queryAsMember: notAvailable("dispatch.queryAsMember"),
+            queryProjection: notAvailable("dispatch.queryProjection"),
+            ...opts?.dispatch,
+        },
+        events: {
+            append: notAvailable("events.append"),
+            unsafeAppend: notAvailable("events.unsafeAppend"),
+            tryAppend: notAvailable("events.tryAppend"),
+            fetchForWriting: notAvailable("events.fetchForWriting"),
+            load: notAvailable("events.load"),
+            archive: notAvailable("events.archive"),
+            restore: notAvailable("events.restore"),
+            isArchived: notAvailable("events.isArchived"),
+            snapshot: notAvailable("events.snapshot"),
+            loadWithSnapshot: notAvailable("events.loadWithSnapshot"),
+        },
+        auth: {
+            resolveClaims: notAvailable("auth.resolveClaims"),
+            resolveActiveMembership: notAvailable("auth.resolveActiveMembership"),
+        },
         // Stub defaults to always-enabled — matches the dispatcher's behaviour
         // when no effectiveFeatures resolver is wired (tests without toggles).
         hasFeature: async () => true,
-        metrics: createNoopMetricsHandle(),
-        metricsFor: () => createNoopMetricsHandle(),
-        tracer: noopTracer,
+        obs: {
+            log: opts?.log ?? createFallbackFullLogger("bridge-stub"),
+            tracer: noopTracer,
+            metrics: createNoopMetricsHandle(),
+            metricsFor: () => createNoopMetricsHandle(),
+        },
         // Real TzContext, not notAvailable — test code uses ctx.tz routinely,
         // it isn't a "bridge" concept. Defaults to UTC.
         tz: createTzContext(),
         // Same reasoning as tz above — ctx.locale is always-present, not a
         // bridge method. Defaults to DEFAULT_LOCALE.
         locale: DEFAULT_LOCALE,
+        services: { extensions: {}, ...opts?.services },
+        lifecycle: {},
+        tenants: {},
     };
 }

package/dist/engine/build-app-schema.d.ts

@@ -1,5 +1,6 @@
-import type { AppSchema } from "../ui-types/index.ts";
+import type { AppSchema, WorkspaceSchema } from "../ui-types/index.ts";
 import type { Registry } from "./types/feature.ts";
+export declare function workspaceOwnerOf(definition: WorkspaceSchema["definition"]): string | undefined;
 export type BuildAppSchemaOptions = {
     /** Dev-server authoring hints (Settings-Hub placement). Default off — only
      *  `createKumikoServer` opts in; prod boot + unit tests stay silent. */

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

@@ -31,6 +31,12 @@ import { isEncryptedAtRest } from "./config-helpers.js";
 import { isListQueryWithoutSearchableFields } from "./entity-list-searchability.js";
 import { QnTypes, qualifyEntityName } from "./qualified-name.js";
 const log = createFallbackLogger("kumiko");
+// Workspace ids are only unique per feature, and the schema carries the short id. The owner stays
+// off the serialized schema; the tenant-level feature strip reads it from here by object identity.
+const workspaceOwnerByDefinition = new WeakMap();
+export function workspaceOwnerOf(definition) {
+    return workspaceOwnerByDefinition.get(definition);
+}
 export function buildAppSchema(registry, options = {}) {
     const features = [];
     const urlPrefillFieldsByScreenQn = collectUrlPrefillFieldsByScreenQn([
@@ -74,8 +80,10 @@ export function buildAppSchema(registry, options = {}) {
     for (const [featureName, feature] of registry.features) {
         for (const [shortId, definition] of Object.entries(feature.workspaces)) {
             const qualified = `${featureName}:workspace:${shortId}`;
+            const projectedDefinition = { ...definition, id: shortId };
+            workspaceOwnerByDefinition.set(projectedDefinition, featureName);
             workspaces.push({
-                definition: { ...definition, id: shortId },
+                definition: projectedDefinition,
                 navMembers: registry.getWorkspaceNavs(qualified),
             });
         }

package/dist/engine/build-config-feature-schema.js

@@ -656,8 +656,13 @@ function buildScreen(shortId, scope, feature, keys, access, hub, options = {}) {
     // feature's group (100% of today's apps — byte-identical output). Only a
     // cross-feature `group` (feature !== ownerFeature) needs the owner prefix,
     // to keep two features sharing a group from clobbering the same shortKey.
+    // A selector's option labels hang on its field id in one global key space
+    // (`config:entity:__config-edit__:field:<id>:option:<value>`), so two owners
+    // whose selector is both named `provider` need distinct ids.
     const fieldId = options.fieldIdOf ??
-        ((k) => (k.feature === k.ownerFeature ? k.shortKey : qualifiedFieldId(k)));
+        ((k) => k.feature === k.ownerFeature && !hub.selectorOptions.has(k.qn)
+            ? k.shortKey
+            : qualifiedFieldId(k));
     const seenFieldIds = new Map();
     for (const k of keys) {
         const id = fieldId(k);

package/dist/engine/config-helpers.d.ts

@@ -1,4 +1,5 @@
-import type { ConfigBacking, ConfigBounds, ConfigComputedFn, ConfigKeyDefinition, ConfigKeyType, ConfigMask, ConfigSeedDef, ConfigValidateFn, ConfigValue, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, OptionsQueryPayload } from "./types/index.ts";
+import type { ConfigBacking, ConfigBounds, ConfigComputedFn, ConfigKeyDefinition, ConfigKeyType, ConfigMask, ConfigSeedDef, ConfigValidateFn, ConfigValue, CreateSeedOptions, CreateTenantSeedOptions } from "@cosmicdrift/kumiko-types/config";
+import type { OptionsQueryPayload } from "@cosmicdrift/kumiko-types/fields";
 export declare function isEncryptedAtRest(def: Pick<ConfigKeyDefinition, "encrypted" | "backing">): boolean;
 export declare const access: {
     readonly all: readonly string[];
@@ -41,5 +42,4 @@ export declare function createUserConfig<T extends ConfigKeyType>(type: T, opts?
 export declare function createSeed(opts: CreateSeedOptions): ConfigSeedDef;
 export declare function createSystemSeed(opts: CreateSeedOptions): ConfigSeedDef;
 export declare function createTenantSeed(opts: CreateSeedOptions, options?: CreateTenantSeedOptions): ConfigSeedDef;
-export declare function createUserSeed(opts: CreateSeedOptions, options: CreateUserSeedOptions): ConfigSeedDef;
 export {};

package/dist/engine/config-helpers.js

@@ -114,12 +114,3 @@ export function createTenantSeed(opts, options) {
 // User-scope seed. Both tenantId AND userId are required — the resolver
 // matches against the user's actual tenantId, so a seed under
 // SYSTEM_TENANT_ID would never resolve.
-export function createUserSeed(opts, options) {
-    return {
-        value: opts.value,
-        scope: "user",
-        key: "",
-        tenantId: options.tenantId,
-        userId: options.userId,
-    };
-}

package/dist/engine/constants.d.ts

@@ -5,24 +5,14 @@ import type { TenantId } from "./types/identifiers.ts";
 export declare const SystemHookNames: {
     readonly cascadeDelete: "system:hook:cascade-delete";
 };
-export type SystemHookName = (typeof SystemHookNames)[keyof typeof SystemHookNames];
 export declare const SystemHookPriorities: {
     readonly cascadeDelete: 500;
 };
-export declare const MessageKind: {
-    readonly write: "write";
-    readonly query: "query";
-    readonly command: "command";
-    readonly shared: "shared";
-    readonly broadcast: "broadcast";
-};
-export type MessageKind = (typeof MessageKind)[keyof typeof MessageKind];
 export declare const LifecycleHookTypes: {
     readonly preSave: "preSave";
     readonly postSave: "postSave";
     readonly preDelete: "preDelete";
     readonly postDelete: "postDelete";
-    readonly preQuery: "preQuery";
     readonly postQuery: "postQuery";
 };
 export type LifecycleHookType = (typeof LifecycleHookTypes)[keyof typeof LifecycleHookTypes];

package/dist/engine/constants.js

@@ -12,20 +12,12 @@ export const SystemHookPriorities = {
     cascadeDelete: 500,
 };
 // --- Message Kinds ---
-export const MessageKind = {
-    write: "write",
-    query: "query",
-    command: "command",
-    shared: "shared",
-    broadcast: "broadcast",
-};
 // --- Lifecycle Hook Types ---
 export const LifecycleHookTypes = {
     preSave: "preSave",
     postSave: "postSave",
     preDelete: "preDelete",
     postDelete: "postDelete",
-    preQuery: "preQuery",
     postQuery: "postQuery",
 };
 // --- Config Scopes ---

package/dist/engine/create-app.js

@@ -1,7 +1,7 @@
 import { validateBoot } from "./boot-validator.js";
 import { dedupeFeatures } from "./dedupe-features.js";
+import { DEFAULT_CURRENCIES } from "./field-helpers.js";
 import { createRegistry } from "./registry.js";
-import { DEFAULT_CURRENCIES } from "./types/index.js";
 // Every field map an entity-less inline form screen renders: actionForm's and
 // secretMint's own fields, plus a secretMint's separate `confirm` step.
 function inlineFormFieldMaps(screen) {

package/dist/engine/define-feature.d.ts

@@ -1,4 +1,5 @@
-import type { FeatureDefinition, FeatureRegistrar } from "./types/index.ts";
+import type { FeatureRegistrar } from "@cosmicdrift/kumiko-types/feature-registrar";
+import type { FeatureDefinition } from "./types/index.ts";
 export type DefineFeatureSettings = {
     readonly dedupeOptions?: Readonly<Record<string, unknown>>;
 };

package/dist/engine/define-feature.js

@@ -12,7 +12,7 @@ import { isObjectArgument, throwObjectArgumentRequired, unwrapArrayForm } from "
 // the call-site (`defineFeature("driverOrders", ...)` → TName="driverOrders").
 // The literal threads into the FeatureRegistrar so r.defineEvent's return
 // carries `name: "driver-orders:event:foo"` as a literal — strict-mode
-// for `ctx.appendEvent({ type: eventDef.name, ... })` lights up. Apps
+// for `ctx.events.append({ type: eventDef.name, ... })` lights up. Apps
 // that don't care can keep the default-string and use the wrapper-based
 // strict-mode (string-literal types per call-site) like before.
 // optionalRequires accepts either variadic strings or a single `{ features }` object; requires
@@ -77,6 +77,9 @@ export function defineFeature(name, setup, settings) {
             }
             state.toggleableDefault = options.default;
         },
+        adoptsBundledLists() {
+            state.adoptsBundledLists = true;
+        },
         uiHints(hints) {
             if (state.uiHints !== undefined) {
                 throw new Error(`[Feature ${name}] r.uiHints() called twice — UI hints are declared once`);
@@ -98,6 +101,7 @@ export function defineFeature(name, setup, settings) {
         requiredProjections: state.requiredProjections,
         requiredSteps: state.requiredSteps,
         ...(state.toggleableDefault !== undefined && { toggleableDefault: state.toggleableDefault }),
+        ...(state.adoptsBundledLists && { adoptsBundledLists: true }),
         ...(state.uiHints !== undefined && { uiHints: state.uiHints }),
         entities: state.entities,
         entityTables: state.entityTables,
@@ -112,7 +116,6 @@ export function defineFeature(name, setup, settings) {
             postSave: state.phasedLifecycleHooks.postSave,
             preDelete: state.phasedLifecycleHooks.preDelete,
             postDelete: state.phasedLifecycleHooks.postDelete,
-            preQuery: state.lifecycleHooks["preQuery"] ?? {},
             postQuery: state.lifecycleHooks["postQuery"] ?? {},
             // @cast-boundary engine-bridge — hook registration erases the per-slot
             // signatures to LifecycleHookFn (a union; see the cast in

package/dist/engine/define-handler.d.ts

@@ -1,8 +1,8 @@
 import type { CursorResult } from "@cosmicdrift/kumiko-types/cursor-types";
+import type { KumikoEventTypeMap } from "@cosmicdrift/kumiko-types/event-type-map";
 import type { ZodType } from "zod";
 import type { ContainsSecret } from "../secrets/types.ts";
 import type { QueryHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput } from "./types/define-handler.ts";
-import type { KumikoEventTypeMap } from "./types/index.ts";
 export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput, } from "./types/define-handler.ts";
 export declare function defineWriteHandler<const TName extends string, TSchema extends ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap, TPrepared = undefined>(def: WriteHandlerInput<TName, TSchema, TData, TMap, TPrepared>, ..._noSecretInResponse: true extends ContainsSecret<TData> ? [
     secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field."

package/dist/engine/define-step.d.ts

@@ -1,4 +1,3 @@
 import type { StepDef, StepKind } from "./types/step.ts";
 export declare function defineStep<TArgs, TResult>(def: StepDef<TArgs, TResult>): StepDef<TArgs, TResult>;
 export declare function getStep(kind: StepKind): StepDef | undefined;
-export declare function listStepKinds(): readonly StepKind[];

package/dist/engine/define-step.js

@@ -17,6 +17,3 @@ export function defineStep(def) {
 export function getStep(kind) {
     return stepRegistry.get(kind);
 }
-export function listStepKinds() {
-    return Array.from(stepRegistry.keys());
-}

package/dist/engine/embedded-derived.d.ts

@@ -1,4 +1,4 @@
-import type { EmbeddedDerivedCellDef, EmbeddedSubFieldDef } from "./types/index.ts";
+import type { EmbeddedDerivedCellDef, EmbeddedSubFieldDef } from "@cosmicdrift/kumiko-types/fields";
 /** Computes a derived cell from its source values. Missing/non-numeric
  *  sources: "multiply"/"percent" with any missing source → undefined; "sum"/"subtract"
  *  treat missing as 0 only when at least one source is present — if every

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

@@ -1,8 +1,9 @@
+import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
+import type { AccessRule, EscapeHatchDeclaration, QueryHandlerDef, WriteHandlerDef } from "@cosmicdrift/kumiko-types/handlers";
 import * as z from "zod";
 import { type EventStoreExecutor } from "../db/event-store-executor.ts";
 import { type EntityRow, type EntityTable } from "../db/table-builder.ts";
 import type { EntityCrudRegistrar, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions } from "./types/entity-handlers.ts";
-import type { AccessRule, EntityDefinition, EscapeHatchDeclaration, QueryHandlerDef, WriteHandlerDef } from "./types/index.ts";
 export type { EntityCrudHandlerDefaults, EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "./types/entity-handlers.ts";
 export declare function assertEscapeHatchAccessIsSystemAdminOnly(name: string, kind: "write" | "query", access: AccessRule): void;
 export declare const MAX_LIST_LIMIT = 200;

package/dist/engine/entity-handlers.js

@@ -41,7 +41,7 @@ import { parseTenantId } from "./types/identifiers.js";
 //     r.queryHandler(defineEntityDetailHandler("note", noteEntity, { access }))
 //
 // For custom logic (default values, business rules, side effects, custom
-// executors with ctx.searchAdapter, ...) write the handler explicitly with
+// executors with ctx.services.searchAdapter, ...) write the handler explicitly with
 // r.writeHandler / r.queryHandler — these helpers cover the standard path only.
 //
 // Note on the `as` casts in the handler bodies: WriteHandlerDef.handler's
@@ -252,7 +252,7 @@ export function defineEntityWriteHandler(name, entity, options) {
         case "create":
             schema = buildInsertSchema(entity, undefined, excludedFields, { allowCallerId: true });
             handler = async (event, ctx) => {
-                const { runPreSave } = ctx;
+                const { lifecycle: { runPreSave }, } = ctx;
                 // A caller-chosen id (deterministic-id idempotent creates) is only
                 // honored for a system-identity caller (jobs/hooks via
                 // createSystemUser) — an HTTP-authenticated end user can never
@@ -273,7 +273,7 @@ export function defineEntityWriteHandler(name, entity, options) {
                 changes: buildUpdateSchema(entity, undefined, excludedFields),
             });
             handler = async (event, ctx) => {
-                const { runPreSave } = ctx;
+                const { lifecycle: { runPreSave }, } = ctx;
                 const db = dbFor(ctx);
                 const submitted = event.payload; // @cast-boundary engine-payload
                 const payload = {
@@ -509,7 +509,7 @@ export function createEntityExecutor(entityName, entity) {
 //   );
 //
 // For anything more involved (filters, joins, custom shaping), write the
-// query-handler explicitly with ctx.queryProjection or a raw select.
+// query-handler explicitly with ctx.dispatch.queryProjection or a raw select.
 export function defineProjectionQueryHandler(name, projectionQualifiedName, options) {
     if (typeof options.unsafeAllTenants === "object") {
         assertReason(`"${name}": unsafeAllTenants`, options.unsafeAllTenants.reason);
@@ -521,11 +521,11 @@ export function defineProjectionQueryHandler(name, projectionQualifiedName, opti
     return {
         name,
         schema: z.object({}),
-        // Returns the raw row array — matches ctx.queryProjection's shape so the
-        // helper is a drop-in for the inline `async (_q, ctx) => ctx.queryProjection(...)`
+        // Returns the raw row array — matches ctx.dispatch.queryProjection's shape so the
+        // helper is a drop-in for the inline `async (_q, ctx) => ctx.dispatch.queryProjection(...)`
         // handler. Wrap the result in the caller's handler when you need
         // pagination envelopes or added metadata.
-        handler: async (_query, ctx) => ctx.queryProjection(projectionQualifiedName, options.unsafeAllTenants ? { unsafeAllTenants: true } : undefined), // @wrapper-known semantic-alias
+        handler: async (_query, ctx) => ctx.dispatch.queryProjection(projectionQualifiedName, options.unsafeAllTenants ? { unsafeAllTenants: true } : undefined), // @wrapper-known semantic-alias
         access: options.access,
         ...(escapeHatch && { escapeHatch }),
     };