@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

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),
             });
         }
@@ -111,7 +119,7 @@ export function buildAppSchema(registry, options = {}) {
         // instead so a leaked function renderer is actually caught.
         const offender = findNonJsonSafePath(schema, "schema");
         if (offender !== null) {
-            log.error(`buildAppSchema: Output ist nicht JSON-safe — nicht-serialisierbarer Wert bei "${offender}" (Funktions-Renderer oder Klassen-Instanz im Schema?).`, { offender });
+            log.error(`buildAppSchema: output is not JSON-safe, non-serializable value at "${offender}" (a function renderer or class instance in the schema?).`, { offender });
         }
     }
     return schema;
@@ -446,136 +454,96 @@ function assertValidScreenMultilineRows(featureName, shortId, screen) {
             check(screen.confirm.fields);
     }
 }
-// Per-field whitelist. Every forwarded value must be JSON-safe (literal, or
-// an array/plain-object built only from JSON-safe values) — even though the
-// FieldDefinition types only type `default` as a literal, the sample-authoring
-// pattern `as unknown as EntityDefinition` has already let function-valued
-// defaults slip through. This whitelist is defense-in-depth that catches them
-// BEFORE JSON.stringify silently drops them in the browser-injection pipeline.
-// The same check gates the structured properties below (`multiline`,
-// `derived`, `totals`, `totalsMatch`) — a top-level `Array.isArray`/plain-
-// object check alone would let a function survive one level deep.
-//
-// Cast at the exit `as EntityFieldDefinition`: type-system-wise our out-map only
-// satisfies the discriminated union with an unnarrowed `type` string — the
-// cast bridges the variant inference TS can't recompute from a generic
-// Record.
-// kumiko-lint-ignore complexity-budget flat per-property whitelist walk, one independent `if` per FieldDefinition property — same shape as schema-builder.ts's field→zod switch
-function projectField(fieldDef) {
-    const def = fieldDef; // @cast-boundary schema-walk
-    const out = {};
-    if (typeof def["type"] === "string")
-        out["type"] = def["type"];
-    if (typeof def["required"] === "boolean")
-        out["required"] = def["required"];
-    if (typeof def["sortable"] === "boolean")
-        out["sortable"] = def["sortable"];
+const isStringValue = (value) => typeof value === "string";
+const isBooleanValue = (value) => typeof value === "boolean";
+const isNumberValue = (value) => typeof value === "number";
+const isTrueValue = (value) => value === true;
+const isNumberOrStringValue = (value) => typeof value === "number" || typeof value === "string";
+const isBooleanOrJsonSafeObject = (value) => typeof value === "boolean" || isJsonSafeObject(value);
+const isUnitSpec = (value) => typeof value === "string" || (isPlainObject(value) && typeof value["field"] === "string");
+// Forwarded in this order, so the client schema keeps its key order.
+const FORWARDED_FIELD_PROPERTIES = [
+    ["type", isStringValue],
+    ["required", isBooleanValue],
+    ["sortable", isBooleanValue],
     // filterable controls the faceted filter dropdowns in the renderer (select/
     // boolean), so it must be included in the client schema.
-    if (typeof def["filterable"] === "boolean")
-        out["filterable"] = def["filterable"];
-    if (typeof def["searchable"] === "boolean")
-        out["searchable"] = def["searchable"];
-    if (isJsonSafeValue(def["default"]))
-        out["default"] = def["default"];
+    ["filterable", isBooleanValue],
+    ["searchable", isBooleanValue],
+    ["default", isJsonSafeValue],
     // Select: the options list is plain JSON, so forward it.
-    if (Array.isArray(def["options"]))
-        out["options"] = def["options"];
-    if (isJsonSafeObject(def["optionTones"]))
-        out["optionTones"] = def["optionTones"];
+    ["options", Array.isArray],
+    ["optionTones", isJsonSafeObject],
     // Reference: entity target, labelField, and multiple are required by the
     // renderer. ReferenceInput builds the options query from refEntity/refFeature
     // and resolves the label through labelField; without these properties, the
     // dropdown is empty (the QN becomes `<feature>:query::list` → 404).
-    if (typeof def["entity"] === "string")
-        out["entity"] = def["entity"];
-    if (typeof def["labelField"] === "string")
-        out["labelField"] = def["labelField"];
+    ["entity", isStringValue],
+    ["labelField", isStringValue],
     // Author-supplied picker source — without it the client falls back to the list handler.
-    if (typeof def["optionsQuery"] === "string")
-        out["optionsQuery"] = def["optionsQuery"];
+    ["optionsQuery", isStringValue],
     // Select: tier/tenant availability of the static options, loaded by the renderer.
-    if (typeof def["optionsAvailabilityQuery"] === "string")
-        out["optionsAvailabilityQuery"] = def["optionsAvailabilityQuery"];
+    ["optionsAvailabilityQuery", isStringValue],
     // 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"];
+    ["conditionalOptions", Array.isArray],
+    ["multiple", isBooleanValue],
     // MultiSelect: display picks checkboxes vs. combobox in the renderer,
     // columns/maxRows size the checkbox grid — without these the renderer
     // always falls back to the combobox. Select: display picks
     // "radio" | "dropdown" the same way.
-    if (typeof def["display"] === "string")
-        out["display"] = def["display"];
-    if (typeof def["columns"] === "number")
-        out["columns"] = def["columns"];
-    if (typeof def["maxRows"] === "number")
-        out["maxRows"] = def["maxRows"];
+    ["display", isStringValue],
+    ["columns", isNumberValue],
+    ["maxRows", isNumberValue],
     // text/longText: textarea row count — DefaultInput renders a single-line
     // input otherwise.
-    if (typeof def["multiline"] === "boolean" || isJsonSafeObject(def["multiline"]))
-        out["multiline"] = def["multiline"];
+    ["multiline", isBooleanOrJsonSafeObject],
     // number: Zod write-boundary bounds. date/timestamp/locatedTimestamp:
     // ISO-string picker bounds — same keys, different literal type.
-    if (typeof def["min"] === "number" || typeof def["min"] === "string")
-        out["min"] = def["min"];
-    if (typeof def["max"] === "number" || typeof def["max"] === "string")
-        out["max"] = def["max"];
+    ["min", isNumberOrStringValue],
+    ["max", isNumberOrStringValue],
     // date/timestamp/locatedTimestamp: display/parsing locale override.
-    if (typeof def["locale"] === "string")
-        out["locale"] = def["locale"];
+    ["locale", isStringValue],
     // image/images: which camera a mobile capture opens.
-    if (typeof def["capture"] === "string")
-        out["capture"] = def["capture"];
+    ["capture", isStringValue],
     // number: display-only suffix, static or read from a sibling field of the row.
-    const unit = def["unit"];
-    if (typeof unit === "string" || (isPlainObject(unit) && typeof unit["field"] === "string"))
-        out["unit"] = unit;
+    ["unit", isUnitSpec],
     // number/decimal/bigInt: `false` drops thousands separators (e.g. a year).
-    if (typeof def["grouping"] === "boolean")
-        out["grouping"] = def["grouping"];
+    ["grouping", isBooleanValue],
     // text: "password" masks the input and blocks URL prefill in the renderer.
-    if (typeof def["format"] === "string")
-        out["format"] = def["format"];
+    ["format", isStringValue],
     // Write-response redaction stays server-side; the renderer needs the flag to
     // refuse any prefill (URL or handoff) into the field.
-    if (def["sensitive"] === true)
-        out["sensitive"] = true;
+    ["sensitive", isTrueValue],
     // Without it the renderer shows a plain text input for a field whose value never leaves the server.
-    if (def["writeOnly"] === true)
-        out["writeOnly"] = true;
+    ["writeOnly", isTrueValue],
     // timestamp: the edit view-model derives its wall-clock input mode from this.
-    if (typeof def["locatedBy"] === "string")
-        out["locatedBy"] = def["locatedBy"];
+    ["locatedBy", isStringValue],
     // file/image/images: upload picker constraints; the first variant key picks
     // the preview variant.
-    if (isJsonSafeArray(def["accept"]))
-        out["accept"] = def["accept"];
-    if (typeof def["maxSize"] === "string")
-        out["maxSize"] = def["maxSize"];
-    if (isJsonSafeObject(def["variants"]))
-        out["variants"] = def["variants"];
+    ["accept", isJsonSafeArray],
+    ["maxSize", isStringValue],
+    ["variants", isJsonSafeObject],
     // decimal, incl. embedded sub-fields: rounding of derived embedded-list cells.
-    if (typeof def["scale"] === "number")
-        out["scale"] = def["scale"];
+    ["scale", isNumberValue],
     // money: declared currency source (MoneyCurrencySource) — without
     // it the renderer can't tell a "currency: { kind: 'tenant' }" field apart
     // from an undeclared one and always falls back to entity.defaultCurrency.
-    if (isJsonSafeObject(def["currency"]))
-        out["currency"] = def["currency"];
+    ["currency", isJsonSafeObject],
     // embedded lists: row-count bounds, computed cells, totals row, and the
     // sibling-money-field totals check.
-    if (typeof def["minItems"] === "number")
-        out["minItems"] = def["minItems"];
-    if (typeof def["maxItems"] === "number")
-        out["maxItems"] = def["maxItems"];
-    if (isJsonSafeObject(def["derived"]))
-        out["derived"] = def["derived"];
-    if (isJsonSafeArray(def["totals"]))
-        out["totals"] = def["totals"];
-    if (isJsonSafeObject(def["totalsMatch"]))
-        out["totalsMatch"] = def["totalsMatch"];
+    ["minItems", isNumberValue],
+    ["maxItems", isNumberValue],
+    ["derived", isJsonSafeObject],
+    ["totals", isJsonSafeArray],
+    ["totalsMatch", isJsonSafeObject],
+];
+function projectField(fieldDef) {
+    const def = fieldDef; // @cast-boundary schema-walk
+    const out = {};
+    for (const [key, isForwarded] of FORWARDED_FIELD_PROPERTIES) {
+        if (isForwarded(def[key]))
+            out[key] = def[key];
+    }
     // embedded lists: the sub-field map itself — without it the client-side
     // edit view-model iterates `undefined` and the screen crashes.
     // Recursive per sub-field, NOT a blanket isJsonSafeValue gate: a single

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/define-feature.js

@@ -48,9 +48,16 @@ export function defineFeature(name, setup, settings) {
         },
         requires: (() => {
             const fn = (...args) => {
-                if (!args.every(isObjectArgument))
+                const [first, ...rest] = args;
+                if (rest.length > 0 || !isObjectArgument(first)) {
                     throwObjectArgumentRequired(name, "requires");
-                state.requires.push(...resolveFeatureNamesArgs(args));
+                }
+                // Untyped callers can pass `{ feature: [...] }`; without this the object would be
+                // registered as a dependency name.
+                if (!Array.isArray(first.features) || !first.features.every((f) => typeof f === "string")) {
+                    throw new Error(`[Feature ${name}] r.requires() needs { features: string[] }`);
+                }
+                state.requires.push(...first.features);
             };
             return Object.assign(fn, {
                 projection: (tableName) => {
@@ -70,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`);
@@ -91,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,

package/dist/engine/define-handler.js

@@ -57,6 +57,7 @@ export function defineWriteHandler(def,
         ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
         ...(def.rateLimit && { rateLimit: def.rateLimit }),
         ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
+        ...(def.rateLimitCost && { rateLimitCost: def.rateLimitCost }),
         ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
         ...pickPreTransactionPhases(def),
         ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),

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

@@ -44,6 +44,19 @@ export declare const entityListSchema: z.ZodObject<{
         }>;
         value: z.ZodUnknown;
     }, z.core.$strip>>>;
+    aggregate: z.ZodOptional<z.ZodObject<{
+        groupBy: z.ZodOptional<z.ZodString>;
+        measures: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            kind: z.ZodEnum<{
+                avg: "avg";
+                count: "count";
+                max: "max";
+                min: "min";
+                sum: "sum";
+            }>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare function defineEntityWriteHandler(name: string, entity: EntityDefinition, options: EntityWriteHandlerOptions): WriteHandlerDef;
 export declare function defineEntityQueryHandler(name: string, entity: EntityDefinition, options: EntityQueryHandlerOptions): QueryHandlerDef;

package/dist/engine/entity-handlers.js

@@ -1,13 +1,16 @@
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
+import { listAggregatePayloadSchema, } from "@cosmicdrift/kumiko-types/list-aggregate-types";
 import * as z from "zod";
 import { collectReferenceFields, enrichRowWithReferences, enrichWithReferences, } from "../db/eagerload.js";
 import { createEventStoreExecutor } from "../db/event-store-executor.js";
+import { answerListAggregate } from "../db/list-aggregate-labels.js";
 import { buildEntityTable } from "../db/table-builder.js";
 import { acknowledgeConventionCrossTenant, reportConventionCrossTenantUse, } from "../db/tenant-db.js";
 import { InternalError } from "../errors/index.js";
 import { isSystemIdentity } from "../pipeline/system-identity-switch.js";
 import { assertUnreachable } from "../utils/index.js";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler.js";
+import { entityListRuntime } from "./entity-list-runtime-options.js";
 import { assertReason } from "./escape-hatch-reason.js";
 import { dropEmptyWriteOnlyValues } from "./field-access.js";
 import { instructionFieldNames } from "./instruction-fields.js";
@@ -105,6 +108,7 @@ export const entityListSchema = z.object({
         value: z.unknown(),
     }))
         .optional(),
+    aggregate: listAggregatePayloadSchema.optional(),
 });
 function parseHandlerName(name, validVerbs) {
     const colonIdx = name.indexOf(":");
@@ -390,28 +394,13 @@ export function defineEntityQueryHandler(name, entity, options) {
                 // runtime override supplies it.
                 const listPayload = query.payload; // @cast-boundary engine-payload
                 const db = dbFor(ctx);
-                const result = await executor.list(listPayload, query.user, db, {
-                    ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
-                    ...(ctx.includeDeleted === true && { includeDeleted: true }),
-                    // Registry access only exists at request time, so the
-                    // searchable-reference cache + entity resolver travel through the
-                    // same runtime-override extension point as searchAdapter above.
-                    referenceSearch: {
-                        fields: ctx.registry.getSearchableReferences(entityName),
-                        resolveEntity: (name) => ctx.registry.getEntity(name),
-                    },
-                    referenceSort: {
-                        fields: ctx.registry.getSortableReferences(entityName),
-                        resolveEntity: (name) => ctx.registry.getEntity(name),
-                    },
-                    parentVisibility: { entities: ctx.registry.getAllEntities() },
-                });
-                const eagerLoadViewer = {
-                    user: query.user,
-                    parentVisibility: { entities: ctx.registry.getAllEntities() },
-                };
+                const { runtimeOptions, eagerLoadViewer, resolveEntity } = entityListRuntime(ctx, entityName, query.user);
+                if (listPayload.aggregate !== undefined) {
+                    return answerListAggregate(executor, { ...listPayload, aggregate: listPayload.aggregate }, query.user, db, runtimeOptions, { entity, resolveEntity, viewer: eagerLoadViewer });
+                }
+                const result = await executor.list(listPayload, query.user, db, runtimeOptions);
                 const enrichedRows = hasRefFields
-                    ? await enrichWithReferences(result.rows, entity, (name) => ctx.registry.getEntity(name), db, eagerLoadViewer)
+                    ? await enrichWithReferences(result.rows, entity, resolveEntity, db, eagerLoadViewer)
                     : result.rows;
                 return { ...result, rows: augmentDerivedFields(enrichedRows, entity) };
             };

package/dist/engine/entity-list-runtime-options.d.ts

@@ -0,0 +1,8 @@
+import type { ListRuntimeOptions } from "@cosmicdrift/kumiko-types/event-store-executor-types";
+import type { EagerLoadEntityResolver, EagerLoadViewer } from "../db/eagerload.ts";
+import type { HandlerContext, SessionUser } from "./types/index.ts";
+export declare function entityListRuntime(ctx: HandlerContext, entityName: string, user: SessionUser): {
+    readonly runtimeOptions: ListRuntimeOptions;
+    readonly eagerLoadViewer: EagerLoadViewer;
+    readonly resolveEntity: EagerLoadEntityResolver;
+};

package/dist/engine/entity-list-runtime-options.js

@@ -0,0 +1,18 @@
+// Registry access only exists at request time, so the searchable/sortable-reference
+// caches, the entity resolver and the join-row read gate travel through the
+// runtime-override extension point of the executor verbs.
+export function entityListRuntime(ctx, entityName, user) {
+    const parentVisibility = { entities: ctx.registry.getAllEntities() };
+    const resolveEntity = (name) => ctx.registry.getEntity(name);
+    return {
+        runtimeOptions: {
+            ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
+            ...(ctx.includeDeleted === true && { includeDeleted: true }),
+            referenceSearch: { fields: ctx.registry.getSearchableReferences(entityName), resolveEntity },
+            referenceSort: { fields: ctx.registry.getSortableReferences(entityName), resolveEntity },
+            parentVisibility,
+        },
+        eagerLoadViewer: { user, parentVisibility },
+        resolveEntity,
+    };
+}

package/dist/engine/feature-ast/extractors/handlers.js

@@ -33,6 +33,7 @@ const WRITE_HANDLER_KEY_KINDS = {
     unsafeSkipTransitionGuard: "modeled",
     rateLimit: "modeled",
     additionalRateLimits: "modeled",
+    rateLimitCost: "opaque",
     escapeHatch: "modeled",
     tenantlessAnonymous: "opaque",
     reserveBeforeTransaction: "opaque",

package/dist/engine/feature-ast/extractors/index.d.ts

@@ -5,7 +5,7 @@ export { extractAuthClaims, extractHook, isHookType, readOptionalAccessRule, rea
 export { extractHttpRoute, extractJob, isHttpRouteMethod, } from "./jobs-routes.ts";
 export { collectScreenOpaqueProps, extractMultiStreamProjection, extractProjection, extractScreen, readApplyBodies, readScreenStatic, } from "./projections-screens.ts";
 export { findImportBindingForLocalName, resolveModuleFile, } from "./resolve-import.ts";
-export { extractDescribe, extractOptionalRequires, extractReadsConfig, extractRequires, extractSystemScope, extractToggleable, extractUiHints, } from "./round1.ts";
+export { extractAdoptsBundledLists, extractDescribe, extractOptionalRequires, extractReadsConfig, extractRequires, extractSystemScope, extractToggleable, extractUiHints, } from "./round1.ts";
 export { extractEntity, extractNav, extractRelation, extractWorkspace, } from "./round2.ts";
 export { extractClaimKey, extractConfig, extractMetric, extractReferenceData, extractSecret, extractSecretNamespace, extractTranslations, extractUseExtension, isClaimKeyType, type NamedOptionsResult, readNamedOptions, } from "./round3.ts";
 export { extractBootCheck, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractStoreTable, extractUsesApi, } from "./round5.ts";

package/dist/engine/feature-ast/extractors/index.js

@@ -5,7 +5,7 @@ export { extractAuthClaims, extractHook, isHookType, readOptionalAccessRule, rea
 export { extractHttpRoute, extractJob, isHttpRouteMethod, } from "./jobs-routes.js";
 export { collectScreenOpaqueProps, extractMultiStreamProjection, extractProjection, extractScreen, readApplyBodies, readScreenStatic, } from "./projections-screens.js";
 export { findImportBindingForLocalName, resolveModuleFile, } from "./resolve-import.js";
-export { extractDescribe, extractOptionalRequires, extractReadsConfig, extractRequires, extractSystemScope, extractToggleable, extractUiHints, } from "./round1.js";
+export { extractAdoptsBundledLists, extractDescribe, extractOptionalRequires, extractReadsConfig, extractRequires, extractSystemScope, extractToggleable, extractUiHints, } from "./round1.js";
 export { extractEntity, extractNav, extractRelation, extractWorkspace, } from "./round2.js";
 export { extractClaimKey, extractConfig, extractMetric, extractReferenceData, extractSecret, extractSecretNamespace, extractTranslations, extractUseExtension, isClaimKeyType, readNamedOptions, } from "./round3.js";
 export { extractBootCheck, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractStoreTable, extractUsesApi, } from "./round5.js";

package/dist/engine/feature-ast/extractors/round1.d.ts

@@ -1,10 +1,11 @@
 import type { CallExpression, SourceFile } from "ts-morph";
-import type { DescribePattern, OptionalRequiresPattern, ReadsConfigPattern, RequiresPattern, SystemScopePattern, ToggleablePattern, UiHintsPattern } from "../patterns.ts";
+import type { AdoptsBundledListsPattern, DescribePattern, OptionalRequiresPattern, ReadsConfigPattern, RequiresPattern, SystemScopePattern, ToggleablePattern, UiHintsPattern } from "../patterns.ts";
 import { type ExtractOutput } from "./shared.ts";
 export declare function extractRequires(call: CallExpression, sourceFile: SourceFile): ExtractOutput<RequiresPattern>;
 export declare function extractOptionalRequires(call: CallExpression, sourceFile: SourceFile): ExtractOutput<OptionalRequiresPattern>;
 export declare function extractReadsConfig(call: CallExpression, sourceFile: SourceFile): ExtractOutput<ReadsConfigPattern>;
 export declare function extractSystemScope(call: CallExpression, sourceFile: SourceFile): ExtractOutput<SystemScopePattern>;
+export declare function extractAdoptsBundledLists(call: CallExpression, sourceFile: SourceFile): ExtractOutput<AdoptsBundledListsPattern>;
 export declare function extractUiHints(call: CallExpression, sourceFile: SourceFile): ExtractOutput<UiHintsPattern>;
 export declare function extractDescribe(call: CallExpression, sourceFile: SourceFile): ExtractOutput<DescribePattern>;
 export declare function extractToggleable(call: CallExpression, sourceFile: SourceFile): ExtractOutput<ToggleablePattern>;

package/dist/engine/feature-ast/extractors/round1.js

@@ -39,6 +39,12 @@ export function extractSystemScope(call, sourceFile) {
         source: sourceLocationFromNode(call, sourceFile),
     });
 }
+export function extractAdoptsBundledLists(call, sourceFile) {
+    return ok({
+        kind: "adoptsBundledLists",
+        source: sourceLocationFromNode(call, sourceFile),
+    });
+}
 export function extractUiHints(call, sourceFile) {
     return ok({
         kind: "uiHints",

package/dist/engine/feature-ast/extractors/round2.js

@@ -2,19 +2,36 @@ import { SyntaxKind } from "ts-morph";
 import { describeUnknownFieldType, findUnknownEntityFieldTypes } from "../entity-field-types.js";
 import { sourceLocationFromNode } from "../source-location.js";
 import { fail, isPlainObject, isRawRefSentinel, ok, readDataLiteralNode, readNameLiteral, readNameOrRef, } from "./shared.js";
+function readBackingTableRef(property) {
+    const initializer = property.asKind(SyntaxKind.PropertyAssignment)?.getInitializer() ??
+        property.asKind(SyntaxKind.ShorthandPropertyAssignment)?.getNameNode();
+    const reference = initializer ? readDataLiteralNode(initializer) : undefined;
+    return isRawRefSentinel(reference) ? reference : undefined;
+}
 // `{ name: "x", ...xEntity }` — the definition is a reference the parser cannot
 // inline, so it is kept as a raw-ref sentinel and re-rendered as the same spread.
 // `backingTable` is runtime wiring (a table identifier), not part of the
-// definition data, so it does not take part in the shape check.
+// definition data, so it is carried next to the definition and skipped by the shape check.
 function readSpreadOnlyDefinition(obj) {
-    const properties = obj
-        .getProperties()
-        .filter((property) => property.asKind(SyntaxKind.PropertyAssignment)?.getName() !== "backingTable");
+    const isBackingTable = (property) => {
+        const name = property.asKind(SyntaxKind.PropertyAssignment)?.getName() ??
+            property.asKind(SyntaxKind.ShorthandPropertyAssignment)?.getName();
+        return name === "backingTable";
+    };
+    const allProperties = obj.getProperties();
+    const properties = allProperties.filter((property) => !isBackingTable(property));
     const spread = properties.length === 2 ? properties[1]?.asKind(SyntaxKind.SpreadAssignment) : undefined;
     if (!spread)
         return undefined;
     const reference = readDataLiteralNode(spread.getExpression());
-    return isRawRefSentinel(reference) ? reference : undefined;
+    if (!isRawRefSentinel(reference))
+        return undefined;
+    const backingTableProperty = allProperties.find(isBackingTable);
+    const backingTable = backingTableProperty ? readBackingTableRef(backingTableProperty) : undefined;
+    // A backingTable that is not a plain reference cannot be re-rendered; fall back to the data reader.
+    if (backingTableProperty && !backingTable)
+        return undefined;
+    return { definition: reference, backingTable };
 }
 export function extractEntity(call, sourceFile) {
     const args = call.getArguments();
@@ -32,7 +49,8 @@ export function extractEntity(call, sourceFile) {
         if (!nameInit) {
             return fail("entity", sourceLocationFromNode(call, sourceFile), "object form requires a string-literal `name` property");
         }
-        const definition = readSpreadOnlyDefinition(obj) ?? readDataLiteralNode(obj);
+        const spreadOnly = readSpreadOnlyDefinition(obj);
+        const definition = spreadOnly?.definition ?? readDataLiteralNode(obj);
         if (!isPlainObject(definition)) {
             return fail("entity", sourceLocationFromNode(call, sourceFile), "definition could not be read as a plain object (contains functions or identifiers)");
         }
@@ -49,6 +67,7 @@ export function extractEntity(call, sourceFile) {
             // Field-type membership is checked above; the cast is the extractor's
             // existing narrowing contract (readDataLiteralNode returns unknown).
             definition: defWithoutName,
+            ...(spreadOnly?.backingTable && { backingTable: spreadOnly.backingTable }),
         });
     }
     const entityName = readNameLiteral(first);

package/dist/engine/feature-ast/index.d.ts

@@ -8,7 +8,7 @@ export type { AddAuthClaimsArgs, AddClaimKeyArgs, AddConfigArgs, AddDefineEventA
 export { createFeaturePatcher } from "./patcher.ts";
 export type { PatternChangeIssue, PatternChangesParseResult } from "./pattern-change-schema.ts";
 export { parsePatternChanges } from "./pattern-change-schema.ts";
-export type { AuthClaimsPattern, ClaimKeyPattern, ConfigPattern, DefineEventPattern, Editability, EntityPattern, ExtendsRegistrarPattern, FeaturePattern, FeaturePatternKind, HookPattern, HttpRoutePattern, JobPattern, MetricPattern, MultiStreamProjectionPattern, NavPattern, NotificationPattern, OptionalRequiresPattern, ProjectionPattern, QueryHandlerPattern, ReadsConfigPattern, ReferenceDataPattern, RelationPattern, RequiresPattern, ScreenPattern, SecretNamespacePattern, SecretPattern, StreamHandlerPattern, SystemScopePattern, ToggleablePattern, TranslationsPattern, UnknownPattern, UseExtensionPattern, WorkspacePattern, WriteHandlerPattern, } from "./patterns.ts";
+export type { AdoptsBundledListsPattern, AuthClaimsPattern, ClaimKeyPattern, ConfigPattern, DefineEventPattern, Editability, EntityPattern, ExtendsRegistrarPattern, FeaturePattern, FeaturePatternKind, HookPattern, HttpRoutePattern, JobPattern, MetricPattern, MultiStreamProjectionPattern, NavPattern, NotificationPattern, OptionalRequiresPattern, ProjectionPattern, QueryHandlerPattern, ReadsConfigPattern, ReferenceDataPattern, RelationPattern, RequiresPattern, ScreenPattern, SecretNamespacePattern, SecretPattern, StreamHandlerPattern, SystemScopePattern, ToggleablePattern, TranslationsPattern, UnknownPattern, UseExtensionPattern, WorkspacePattern, WriteHandlerPattern, } from "./patterns.ts";
 export { getEditability } from "./patterns.ts";
 export type { RenderFeatureFileInput } from "./render.ts";
 export { FEATURE_FILE_VERSION, renderFeatureFile, renderPattern, renderValue, VERSION_HEADER, } from "./render.ts";

package/dist/engine/feature-ast/parse.js

@@ -21,7 +21,7 @@
 // Per-pattern extractors fill in iteratively — each iteration adds
 // one extractor + a focused test.
 import { Project, SyntaxKind } from "ts-morph";
-import { extractAiClassify, extractAiExtract, extractAiGenerate, extractAuthClaims, extractBootCheck, extractClaimKey, extractConfig, extractDefineEvent, extractDescribe, extractEntity, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractHook, extractHttpRoute, extractJob, extractMetric, extractMultiStreamProjection, extractNav, extractNotification, extractOptionalRequires, extractProjection, extractQueryHandler, extractReadsConfig, extractReferenceData, extractRelation, extractRequires, extractScreen, extractSecret, extractSecretNamespace, extractStoreTable, extractStreamHandler, extractSystemScope, extractToggleable, extractTranslations, extractTreeActions, extractUiHints, extractUseExtension, extractUsesApi, extractWorkspace, extractWriteHandler, findFunctionLiteral, findImportBindingForLocalName, readObjectPropertyInitializer, resolveModuleFile, resolveSameFileObjectLiteral, } from "./extractors/index.js";
+import { extractAdoptsBundledLists, extractAiClassify, extractAiExtract, extractAiGenerate, extractAuthClaims, extractBootCheck, extractClaimKey, extractConfig, extractDefineEvent, extractDescribe, extractEntity, extractEnvSchema, extractExposesApi, extractExtendsRegistrar, extractHook, extractHttpRoute, extractJob, extractMetric, extractMultiStreamProjection, extractNav, extractNotification, extractOptionalRequires, extractProjection, extractQueryHandler, extractReadsConfig, extractReferenceData, extractRelation, extractRequires, extractScreen, extractSecret, extractSecretNamespace, extractStoreTable, extractStreamHandler, extractSystemScope, extractToggleable, extractTranslations, extractTreeActions, extractUiHints, extractUseExtension, extractUsesApi, extractWorkspace, extractWriteHandler, findFunctionLiteral, findImportBindingForLocalName, readObjectPropertyInitializer, resolveModuleFile, resolveSameFileObjectLiteral, } from "./extractors/index.js";
 import { sourceLocationFromNode } from "./source-location.js";
 /**
  * Parse the given feature file and return all recognised r.* calls
@@ -397,6 +397,8 @@ function dispatchExtractor(methodName, call, sourceFile) {
             return extractDescribe(call, sourceFile);
         case "uiHints":
             return extractUiHints(call, sourceFile);
+        case "adoptsBundledLists":
+            return extractAdoptsBundledLists(call, sourceFile);
         // Object-literal-based static patterns
         case "entity":
             return extractEntity(call, sourceFile);

package/dist/engine/feature-ast/patch.d.ts

@@ -102,6 +102,8 @@ export type PatternId = {
     readonly kind: "describe";
 } | {
     readonly kind: "uiHints";
+} | {
+    readonly kind: "adoptsBundledLists";
 } | {
     readonly kind: "config";
 } | {