@cosmicdrift/kumiko-framework 0.365.1 → 0.366.0

package/agents/examples/state-machine.md

@@ -567,7 +567,7 @@ import type { InvoiceStatus } from "./reducer";
 export { invoiceEntity } from "./entities/invoice";
 
 export const stateMachineFeature = defineFeature("billing", (r) => {
-  r.entity("invoice", invoiceEntity);
+  r.entity({ name: "invoice", ...invoiceEntity });
 
   // Domain events — one per intent. Names live in events.ts so the reducer
   // and the projection stay in sync. The auto "invoice.created" event from

package/agents/examples/tags-basic.md

@@ -85,7 +85,7 @@ See the [tags feature reference](/en/bundled-features/tags/) for the full set.
 tags             → core bundle: tag + tag-assignment entities,
                    create/assign/remove handlers, list queries
 note-management  → our feature: a plain `note` entity. Declares
-                   r.requires("tags") only so the bundle is mounted —
+                   r.requires({ features: ["tags"] }) only so the bundle is mounted —
                    the note itself is completely tag-agnostic.
 ```
 
@@ -321,9 +321,9 @@ export const noteFeature = defineFeature("note-management", (r) => {
   // tags is non-optional for this recipe: the demo tags notes. The note
   // feature itself stays completely tag-agnostic — it only declares the
   // dependency so the bundle is mounted.
-  r.requires("tags");
+  r.requires({ features: ["tags"] });
 
-  r.entity("note", noteEntity);
+  r.entity({ name: "note", ...noteEntity });
 
   r.writeHandler({
     name: "note:create",

package/agents/examples/tenant-settings.md

@@ -35,7 +35,7 @@ export const invoiceEntity = createEntity({
 });
 
 export const invoiceFeature = defineFeature("invoice", (r) => {
-  r.entity("invoice", invoiceEntity);
+  r.entity({ name: "invoice", ...invoiceEntity });
   r.writeHandler(
     defineCreateWithTenantDefaults("invoice", invoiceEntity, {
       access: { roles: ["Admin"] },
@@ -263,7 +263,7 @@ export const invoiceEntity = createEntity({
 const ACCESS = { roles: ["Admin"] } as const;
 
 export const invoiceFeature = defineFeature("invoice", (r) => {
-  r.entity("invoice", invoiceEntity);
+  r.entity({ name: "invoice", ...invoiceEntity });
   r.writeHandler(
     defineCreateWithTenantDefaults("invoice", invoiceEntity, {
       access: ACCESS,

package/agents/examples/timezones.md

@@ -336,12 +336,12 @@ export const timezonesFeature = defineFeature("timezones", (r) => {
   });
   r.writeHandler(defineEntityDeleteHandler("delivery", deliveryEntity, adminWrite));
 
-  r.queryHandler(
-    "day-window",
-    z.object({
+  r.queryHandler({
+    name: "day-window",
+    schema: z.object({
       zone: z.string().refine(isValidIanaTimeZone, { message: "Invalid IANA timezone" }),
     }),
-    async (query, ctx) => {
+    handler: async (query, ctx) => {
       const { start, end } = ctx.tz.todayRange(query.payload.zone);
       return {
         zone: query.payload.zone,
@@ -350,17 +350,17 @@ export const timezonesFeature = defineFeature("timezones", (r) => {
         end: end.toString(),
       };
     },
-    openRead,
-  );
+    ...openRead,
+  });
 
-  r.queryHandler(
-    "zone-at",
-    z.object({ latitude: z.number(), longitude: z.number() }),
-    async (query, ctx) => {
+  r.queryHandler({
+    name: "zone-at",
+    schema: z.object({ latitude: z.number(), longitude: z.number() }),
+    handler: async (query, ctx) => {
       const zone = await ctx.tz.fromCoordinates(query.payload);
       return { zone };
     },
-    openRead,
-  );
+    ...openRead,
+  });
 });
 ```

package/agents/examples/user-data-rights.md

@@ -19,8 +19,8 @@ forget logic:
 
 ```ts illustration
 defineFeature("notes", (r) => {
-  r.requires("user-data-rights");
-  r.entity("note", noteEntity);
+  r.requires({ features: ["user-data-rights"] });
+  r.entity({ name: "note", ...noteEntity });
 
   r.useExtension(EXT_USER_DATA, "note", {
     export: async (ctx) => ({
@@ -375,7 +375,7 @@ export const noteEntity = createEntity({
 export const notesTable = deriveEntityTableMeta("note", noteEntity, { source: "unmanaged" });
 
 export const notesFeature = defineFeature("notes", (r) => {
-  r.requires("user-data-rights");
+  r.requires({ features: ["user-data-rights"] });
   // store_notes is a direct-write store: the forget hook below `updateMany`/
   // `deleteMany`s rows WITHOUT emitting lifecycle events. r.entity would make
   // it a rebuildable implicit projection whose replay finds zero note events

package/agents/examples/user-profile.md

@@ -187,7 +187,7 @@ export function createAccountFeature(): FeatureDefinition {
         "entry — user-profile registers the `profile` screen itself " +
         "(fw#2312 declarative projectionDetail).",
     );
-    r.requires("user-profile");
+    r.requires({ features: ["user-profile"] });
 
     r.nav({
       id: "profile",

package/agents/examples/webhook-step.md

@@ -436,7 +436,7 @@ const incidentExecutor = createEventStoreExecutor(incidentTable, incidentEntity,
 const INCIDENT_HOOK_URL = "https://hooks.example/incident";
 
 export const webhookDemoFeature = defineFeature("webhook-demo", (r) => {
-  r.entity("incident", incidentEntity);
+  r.entity({ name: "incident", ...incidentEntity });
   r.requires.step("webhook.send");
   r.requires.step("mail.send");
   r.requires.step("callFeature");

package/agents/examples/writeform-section.md

@@ -127,10 +127,16 @@ describe("writeform-section sample — boot-validator catches author mistakes",
   test("a writeForm field without its pseudo-entity translation key fails boot", () => {
     const broken = defineFeature("broken-note-desk", (r) => {
       r.translations({ keys: { "screen:x.title": { en: "X" } } });
-      r.queryHandler("foo:detail", z.object({ id: z.string() }), async () => ({}), {
+      r.queryHandler({
+        name: "foo:detail",
+        schema: z.object({ id: z.string() }),
+        handler: async () => ({}),
         access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
-      r.writeHandler("save", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+      r.writeHandler({
+        name: "save",
+        schema: z.object({}),
+        handler: async () => ({ isSuccess: true as const, data: null }),
         access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
       r.screen({
@@ -249,19 +255,19 @@ export const noteDeskFeature = defineFeature("note-desk", (r) => {
     access: open.access,
   });
 
-  r.queryHandler(
-    "note:summary",
-    z.object({ id: z.string() }),
-    async (query) => ({ id: query.payload.id, ...NOTE_DETAIL_FIELDS }),
-    open,
-  );
-
-  r.writeHandler(
-    "note:comment",
-    commentPayloadSchema,
-    async () => ({ isSuccess: true as const, data: null }),
-    open,
-  );
+  r.queryHandler({
+    name: "note:summary",
+    schema: z.object({ id: z.string() }),
+    handler: async (query) => ({ id: query.payload.id, ...NOTE_DETAIL_FIELDS }),
+    ...open,
+  });
+
+  r.writeHandler({
+    name: "note:comment",
+    schema: commentPayloadSchema,
+    handler: async () => ({ isSuccess: true as const, data: null }),
+    ...open,
+  });
 
   r.screen({
     id: "note-detail",

package/agents/widgets.md

@@ -147,6 +147,9 @@ Value exports of `@cosmicdrift/kumiko-renderer-web`.
 | `createKumikoApp` |  |
 | `createPublicSurface` |  |
 | `createStaticLocaleResolver` | Default-Resolver für Apps ohne eigene i18n-Schicht. |
+| `downloadFileRef` |  |
+| `fetchFileRefBlob` |  |
+| `fileNameFromContentDisposition` |  |
 | `filterAppSchemaNavsByAllowlist` |  |
 | `filterByAccess` |  |
 | `formatMoney` |  |
@@ -158,6 +161,7 @@ Value exports of `@cosmicdrift/kumiko-renderer-web`.
 | `readLoadedBuild` |  |
 | `reparentAppSchemaNavs` |  |
 | `resolveDefaultId` |  |
+| `saveBlobAsFile` |  |
 | `smoothPath` | Quadratic-durch-Mittelpunkte-Trick: glättet die Zick-Zack-Linie ohne Overshoot (~5 Zeilen statt Catmull-Rom/Bezier-Fit). |
 | `synthesizeActionFormEntity` | Baut eine minimale EntityDefinition aus den Inline-Fields eines ActionForm- oder SecretMint-Screens. |
 | `synthesizeActionFormScreen` | Wandelt ein ActionFormScreenDefinition oder SecretMintScreenDefinition in die EntityEditScreen-Shape die RenderEdit erwartet. |
@@ -178,4 +182,5 @@ Value exports of `@cosmicdrift/kumiko-renderer-web`.
 
 | Name | Description |
 | --- | --- |
+| `FileDownloadFailedError` |  |
 | `FileUploadFailedError` | Carries the server's own `error` message when the upload endpoint sent one. |

package/dist/api/server.js

@@ -6,6 +6,7 @@ import { buildAppSchema } from "../engine/build-app-schema.js";
 import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names.js";
 import { projectAppSchemaForRoles } from "../engine/project-app-schema-for-roles.js";
 import { runsInLane } from "../engine/run-in.js";
+import { resolveDisabledFeatureNames, stripDisabledFeaturesFromAppSchema, } from "../engine/strip-disabled-features-from-app-schema.js";
 import { createAnonymousUser, createSystemUser, isAnonymousSessionUser, } from "../engine/system-user.js";
 import { isFileField, } from "../engine/types/index.js";
 import { assertSeedModeNotInProduction } from "../event-store/seed-clock.js";
@@ -673,15 +674,22 @@ export function buildServer(options) {
     // not the whole app's schema) and cached per role key. Tenant is
     // deliberately NOT part of the key: the projection depends only on
     // roles, and per-tenant caching would grow unboundedly across tenants
-    // that share the same role set.
+    // that share the same role set. What IS part of the key: the sorted set of
+    // features the caller's tenant has switched off (r.toggleable) — few
+    // distinct sets, so the cache stays small. The resolver is read per request
+    // because run{Dev,Prod}App fill it in after the server is built.
     let fullSchema;
     const projectedSchemaCache = new Map();
-    app.get(`/api${Routes.schema}`, (c) => {
+    app.get(`/api${Routes.schema}`, async (c) => {
         const user = getUser(c);
         if (isMissingOrAnonymousUser(user)) {
             return unauthenticatedResponse(c);
         }
-        const roleKey = JSON.stringify([...new Set(user?.roles ?? [])].sort());
+        const effectiveFeatures = options.dispatcherOptions?.effectiveFeatures;
+        const disabledFeatureNames = effectiveFeatures === undefined
+            ? []
+            : await resolveDisabledFeatureNames(options.registry, effectiveFeatures, user.tenantId);
+        const roleKey = JSON.stringify([[...new Set(user?.roles ?? [])].sort(), disabledFeatureNames]);
         let cached = projectedSchemaCache.get(roleKey);
         if (cached === undefined) {
             if (fullSchema === undefined) {
@@ -689,7 +697,7 @@ export function buildServer(options) {
                     searchAdapterMissing: !options.context.searchAdapter,
                 });
             }
-            const projected = projectAppSchemaForRoles(fullSchema, user?.roles ?? []);
+            const projected = projectAppSchemaForRoles(stripDisabledFeaturesFromAppSchema(fullSchema, options.registry, disabledFeatureNames), user?.roles ?? []);
             const json = JSON.stringify(projected);
             cached = { json, etag: computeStrongEtag(json) };
             projectedSchemaCache.set(roleKey, cached);

package/dist/bun-db/query.js

@@ -861,6 +861,21 @@ export async function unsafeReadRetrying(db, sqlText, params) {
         throw lastErr;
     }
 }
+function selectColumnList(info, fields) {
+    if (fields === undefined)
+        return "*";
+    if (fields.length === 0) {
+        throw new Error(`selectMany: fields must not be empty for "${info.name}"`);
+    }
+    return fields
+        .map((field) => {
+        if (!info.hasColumn(field)) {
+            throw new Error(`selectMany: fields entry "${field}" is not a column of "${info.name}"`);
+        }
+        return quoteIdent(info.columnOf(field));
+    })
+        .join(", ");
+}
 // biome-ignore lint/suspicious/noExplicitAny: opt-in default loosens row type for unannotated test fixtures
 export async function selectMany(db, table, where, options) {
     const scoped = tenantDbDelegate(db);
@@ -868,7 +883,7 @@ export async function selectMany(db, table, where, options) {
         return scoped.selectMany(table, where, options);
     }
     const info = extractTableInfo(table);
-    let sqlText = `SELECT * FROM ${quoteIdent(info.name)}`;
+    let sqlText = `SELECT ${selectColumnList(info, options?.fields)} FROM ${quoteIdent(info.name)}`;
     let values = [];
     if (where && Object.keys(where).length > 0) {
         const w = buildWhereClause(info, where, 1);

package/dist/db/entity-table-meta.js

@@ -358,8 +358,8 @@ export const buildEntityTableMeta = deriveEntityTableMeta;
 function sqlExpressionText(where) {
     return isSqlExpression(where) ? where.text : undefined;
 }
-// Validates that a backing Drizzle table (declared via `r.entity(name, def,
-// { table })`) is a SUPERSET of the field-derived meta: every column the
+// Validates that a backing Drizzle table (declared via `r.entity({ name, ...def,
+// backingTable })`) is a SUPERSET of the field-derived meta: every column the
 // entity fields produce must exist on the table with the same pgType +
 // notNull. Ride-along columns/indexes the table adds on top (envelope,
 // uniqueIndex, …) are exactly the point — they pass. A field with no matching
@@ -371,13 +371,13 @@ export function assertBackingTableSuperset(entityName, fieldMeta, tableMeta) {
     for (const fieldCol of fieldMeta.columns) {
         const tableCol = tableCols.get(fieldCol.name);
         if (!tableCol) {
-            throw new Error(`r.entity("${entityName}", …, { table }): the backing table ` +
+            throw new Error(`r.entity({ name: "${entityName}", …, backingTable }): the backing table ` +
                 `"${tableMeta.tableName}" is missing column "${fieldCol.name}" that the ` +
                 "entity field declares. The table must be a superset of the entity's " +
                 "fields — add the column to the table or remove the field.");
         }
         if (tableCol.pgType !== fieldCol.pgType || tableCol.notNull !== fieldCol.notNull) {
-            throw new Error(`r.entity("${entityName}", …, { table }): column "${fieldCol.name}" ` +
+            throw new Error(`r.entity({ name: "${entityName}", …, backingTable }): column "${fieldCol.name}" ` +
                 `disagrees between entity field (${fieldCol.pgType}, ` +
                 `notNull=${fieldCol.notNull}) and backing table "${tableMeta.tableName}" ` +
                 `(${tableCol.pgType}, notNull=${tableCol.notNull}). Align them.`);

package/dist/engine/boot-validator/api-ext.js

@@ -25,7 +25,7 @@ export function validateApiExposureMatching(feature, allExposedApis, featureMap)
         }
         const allDeps = [...feature.requires, ...feature.optionalRequires];
         if (!allDeps.includes(providerFeature)) {
-            throw new Error(`[Feature ${feature.name}] r.usesApi("${apiName}") is exposed by "${providerFeature}" but feature is not in requires/optionalRequires. Add r.requires("${providerFeature}").`);
+            throw new Error(`[Feature ${feature.name}] r.usesApi("${apiName}") is exposed by "${providerFeature}" but feature is not in requires/optionalRequires. Add r.requires({ features: ["${providerFeature}"] }).`);
         }
         // Sanity: provider feature actually exists in this app's feature set.
         // Should always be true if allExposedApis was built from `features`,
@@ -48,7 +48,7 @@ export function validateExtensionUsages(feature, extensionProviders) {
         }
         const allDeps = [...feature.requires, ...feature.optionalRequires];
         if (!allDeps.includes(providerFeature)) {
-            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" but missing requires("${providerFeature}"). Add r.requires("${providerFeature}").`);
+            throw new Error(`Feature "${feature.name}" uses extension "${usage.extensionName}" but missing requires("${providerFeature}"). Add r.requires({ features: ["${providerFeature}"] }).`);
         }
     }
 }

package/dist/engine/boot-validator/config-deps.js

@@ -2,7 +2,7 @@ import { optionsQueryFieldRefs } from "@cosmicdrift/kumiko-types/fields";
 import { isEncryptedAtRest } from "../config-helpers.js";
 // --- Toggleable-dependency warnings ---
 //
-// When feature A declares r.requires("B") and B is toggleable with
+// When feature A declares r.requires({ features: ["B"] }) and B is toggleable with
 // default=false, A is effectively disabled out-of-the-box until someone
 // flips B on globally. That's usually an oversight — the dev either meant
 // optionalRequires, or forgot to ship B with default=true. We warn (not

package/dist/engine/boot-validator/handler-field-references.js

@@ -1,16 +1,9 @@
-import { readHandlerFieldReference } from "../handler-field-references.js";
+import { readHandlerFieldReferences } from "../handler-field-references.js";
 import { parseRefTarget } from "../parse-ref-target.js";
-import { getZodObjectShape } from "./zod-shape.js";
 function validateHandlerGroup(feature, featureMap, handlers, handlerNoun) {
     for (const [handlerName, def] of Object.entries(handlers)) {
-        const shape = getZodObjectShape(def.schema);
-        if (shape === undefined)
-            continue;
-        for (const fieldName of Object.keys(shape)) {
-            const where = `Input field "${fieldName}" of ${handlerNoun} "${handlerName}"`;
-            const reading = readHandlerFieldReference(def.schema, fieldName);
-            if (reading.kind === "none")
-                continue;
+        for (const { path, reading } of readHandlerFieldReferences(def.schema)) {
+            const where = `Input field "${path}" of ${handlerNoun} "${handlerName}"`;
             if (reading.kind === "invalid") {
                 throw new Error(`[Feature ${feature.name}] ${where} has an invalid meta references value ${JSON.stringify(reading.raw)}. ` +
                     `Use "<entity>", "<feature>:<entity>" or { entity, by? }.`);

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

@@ -2216,7 +2216,7 @@ function assertRefTargetRegistered(prefix, subject, refTarget, currentFeatureNam
     const targetFeature = featureMap.get(target.featureName);
     if (targetFeature === undefined) {
         throw new Error(`${prefix} ${subject} targets entity "${refTarget}", but feature "${target.featureName}" is not ` +
-            `mounted — mount it and declare r.requires("${target.featureName}").`);
+            `mounted — mount it and declare r.requires({ features: ["${target.featureName}"] }).`);
     }
     if (targetFeature.entities?.[target.entityName] === undefined) {
         throw new Error(`${prefix} ${subject} targets entity "${refTarget}", which does not resolve to a ` +

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

@@ -20,12 +20,9 @@
 //   Translations: verbatim feature.translations (raw r.translations keys,
 //                 unfiltered — see FeatureSchema.translations doc)
 //
-// Feature-Toggles: BISHER NICHT GEFILTERT. Wenn ein Feature über die
-// feature-toggles-bundled-feature global deaktiviert ist, erscheint es
-// trotzdem im AppSchema. Reason: die Toggle-Auflösung lebt im pipeline-
-// dispatcher, nicht in der Registry, und wir haben hier keinen TenantDb-
-// Kontext um sie zu lesen. TODO wenn das ein realer Use-Case wird:
-// `effectiveFeatures` Argument annehmen und über alle iterations filtern.
+// Feature toggles: this schema is tenant-independent and lists every feature.
+// The schema route strips features the caller's tenant has switched off
+// (r.toggleable) via stripDisabledFeaturesFromAppSchema.
 import { ZodObject } from "zod";
 import { collectUrlPrefillFieldsByScreenQn } from "./boot-validator/url-prefill-fields.js";
 import { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, } from "./build-config-feature-schema.js";

package/dist/engine/define-feature.js

@@ -2,7 +2,7 @@ import { createInitialFeatureBuilderState } from "./feature-builder-state.js";
 import { buildConfigEventsJobsMethods } from "./feature-config-events-jobs.js";
 import { buildEntityHandlerMethods } from "./feature-entity-handlers.js";
 import { buildUiExtensionsMethods } from "./feature-ui-extensions.js";
-import { unwrapArrayForm } from "./object-form.js";
+import { isObjectArgument, throwPositionalFormRemoved, unwrapArrayForm } from "./object-form.js";
 // `TExports` lets the setup callback hand back a typed object that
 // downstream features can import (e.g. `tenantFeature.exports.config`). The
 // runtime always packs whatever setup returns into `featureDef.exports` —
@@ -15,10 +15,8 @@ import { unwrapArrayForm } from "./object-form.js";
 // for `ctx.appendEvent({ 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.
-// requires/optionalRequires accept either variadic strings (hand-written
-// call sites) or a single `{ features }` object (the feature-ast renderer's
-// canonical Object-Form for Designer/AI-generated code) — see the matching
-// overloads on RequiresApi / FeatureRegistrar['optionalRequires'].
+// optionalRequires accepts either variadic strings or a single `{ features }` object; requires
+// takes only the object (see RequiresApi).
 function resolveFeatureNamesArgs(args) {
     return unwrapArrayForm(args, "features");
 }
@@ -50,6 +48,8 @@ export function defineFeature(name, setup, settings) {
         },
         requires: (() => {
             const fn = (...args) => {
+                if (!args.every(isObjectArgument))
+                    throwPositionalFormRemoved(name, "requires");
                 state.requires.push(...resolveFeatureNamesArgs(args));
             };
             fn.projection = (tableName) => {

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

@@ -63,5 +63,5 @@ export declare function defineProjectionQueryHandler(name: string, projectionQua
     };
     escapeHatch?: EscapeHatchDeclaration;
 }): QueryHandlerDef;
-/** Register standard entity CRUD handlers in one call. Access stays explicit — no openToAll default. */
-export declare function registerEntityCrud(r: EntityCrudRegistrar, entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;
+/** Backs `r.crud`: registers the standard entity CRUD handlers. Access stays explicit — no openToAll default. */
+export declare function registerCrudHandlers(r: EntityCrudRegistrar, entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;

package/dist/engine/entity-handlers.js

@@ -551,21 +551,21 @@ function defaultCrudVerbs(entity) {
         detail: true,
     };
 }
-/** Register standard entity CRUD handlers in one call. Access stays explicit — no openToAll default. */
-export function registerEntityCrud(r, entityName, entity, options) {
+/** Backs `r.crud`: registers the standard entity CRUD handlers. Access stays explicit — no openToAll default. */
+export function registerCrudHandlers(r, entityName, entity, options) {
     const verbs = { ...defaultCrudVerbs(entity), ...options?.verbs };
     if (verbs.restore && entity.softDelete !== true) {
         throw new Error(`restore requested but entity "${entityName}" has no softDelete: true`);
     }
     if (options?.registerEntity !== false) {
-        r.entity(entityName, entity);
+        r.entity({ name: entityName, ...entity });
     }
     const writeOpts = options?.write;
     const readOpts = options?.read;
     const requireAccess = (verb, access) => {
         if (!access) {
-            throw new Error(`registerEntityCrud("${entityName}", verb: "${verb}"): no access rule resolved. ` +
-                `Set write.access/read.access on registerEntityCrud's options, or verbAccess.${verb}.`);
+            throw new Error(`r.crud("${entityName}", …): no access rule resolved for verb "${verb}". ` +
+                `Set write.access/read.access in r.crud's options, or verbAccess.${verb}.`);
         }
         return access;
     };

package/dist/engine/factories.d.ts

@@ -133,34 +133,34 @@ export declare function createTzField<R extends true | false = false>(overrides?
     required: R;
 };
 /**
- * Wall-Clock-Termin an einem Ort als ATOMARES Field. Empfohlene Form für
- * jeden Date-Wert mit Location-Bezug (Pickup, Delivery, Meeting, Schedule).
+ * Wall-clock time at a place as one atomic field. Use it for every date
+ * value tied to a location (pickup, delivery, meeting, schedule).
  *
- * EIN Schema-Feld → ZWEI DB-Spalten (`<name>_utc TIMESTAMPTZ` + `<name>_tz TEXT`)
- * → DREI API-Felder beim Read (`{ at, tz, utc }`).
+ * One schema field maps to two DB columns (`<name>_utc TIMESTAMPTZ` +
+ * `<name>_tz TEXT`) and to three API fields on read (`{ at, tz, utc }`).
  *
  * ```ts
- * r.entity("order", {
+ * r.entity({
+ *   name: "order",
  *   fields: {
  *     pickup: createLocatedTimestampField(),
  *     delivery: createLocatedTimestampField(),
  *   },
  * });
  *
- * // Write — Caller schickt at+tz, Framework rechnet utc aus
+ * // Write: the caller sends at+tz, the framework computes utc
  * await create({ pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" } });
  *
- * // Read — Framework liefert alle drei Felder zurück
+ * // Read: the framework returns all three fields
  * // → { pickup: { at: "10:00", tz: "Europe/Lisbon", utc: "09:00Z" } }
  *
- * // Sort/Filter über die UTC-Spalte
+ * // Sort/filter on the UTC column
  * orderBy(asc(orderTable.pickupUtc))
  * where(between(orderTable.pickupUtc, start, end))
  * ```
  *
- * Default-Sicht für `at` ist Pickup-Ort-lokal (was eingegeben wurde, kommt
- * mit demselben Tag zurück). User-lokale Sicht kommt aus `utc` per
- * separater Berechnung.
+ * `at` is local to the place (what was entered comes back on the same day).
+ * A user-local view is computed separately from `utc`.
  */
 export declare function createLocatedTimestampField<R extends true | false = false>(overrides?: Partial<Omit<LocatedTimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
     required?: R;

package/dist/engine/factories.js

@@ -324,34 +324,34 @@ export function createTzField(overrides) {
     }; // @cast-boundary engine-payload
 }
 /**
- * Wall-Clock-Termin an einem Ort als ATOMARES Field. Empfohlene Form für
- * jeden Date-Wert mit Location-Bezug (Pickup, Delivery, Meeting, Schedule).
+ * Wall-clock time at a place as one atomic field. Use it for every date
+ * value tied to a location (pickup, delivery, meeting, schedule).
  *
- * EIN Schema-Feld → ZWEI DB-Spalten (`<name>_utc TIMESTAMPTZ` + `<name>_tz TEXT`)
- * → DREI API-Felder beim Read (`{ at, tz, utc }`).
+ * One schema field maps to two DB columns (`<name>_utc TIMESTAMPTZ` +
+ * `<name>_tz TEXT`) and to three API fields on read (`{ at, tz, utc }`).
  *
  * ```ts
- * r.entity("order", {
+ * r.entity({
+ *   name: "order",
  *   fields: {
  *     pickup: createLocatedTimestampField(),
  *     delivery: createLocatedTimestampField(),
  *   },
  * });
  *
- * // Write — Caller schickt at+tz, Framework rechnet utc aus
+ * // Write: the caller sends at+tz, the framework computes utc
  * await create({ pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" } });
  *
- * // Read — Framework liefert alle drei Felder zurück
+ * // Read: the framework returns all three fields
  * // → { pickup: { at: "10:00", tz: "Europe/Lisbon", utc: "09:00Z" } }
  *
- * // Sort/Filter über die UTC-Spalte
+ * // Sort/filter on the UTC column
  * orderBy(asc(orderTable.pickupUtc))
  * where(between(orderTable.pickupUtc, start, end))
  * ```
  *
- * Default-Sicht für `at` ist Pickup-Ort-lokal (was eingegeben wurde, kommt
- * mit demselben Tag zurück). User-lokale Sicht kommt aus `utc` per
- * separater Berechnung.
+ * `at` is local to the place (what was entered comes back on the same day).
+ * A user-local view is computed separately from `utc`.
  */
 export function createLocatedTimestampField(overrides) {
     return {

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

@@ -1,7 +1,21 @@
 import { SyntaxKind } from "ts-morph";
 import { describeUnknownFieldType, findUnknownEntityFieldTypes } from "../entity-field-types.js";
 import { sourceLocationFromNode } from "../source-location.js";
-import { fail, isPlainObject, ok, readDataLiteralNode, readNameLiteral, readNameOrRef, } from "./shared.js";
+import { fail, isPlainObject, isRawRefSentinel, ok, readDataLiteralNode, readNameLiteral, readNameOrRef, } from "./shared.js";
+// `{ 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.
+function readSpreadOnlyDefinition(obj) {
+    const properties = obj
+        .getProperties()
+        .filter((property) => property.asKind(SyntaxKind.PropertyAssignment)?.getName() !== "backingTable");
+    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;
+}
 export function extractEntity(call, sourceFile) {
     const args = call.getArguments();
     const first = args[0];
@@ -18,7 +32,7 @@ export function extractEntity(call, sourceFile) {
         if (!nameInit) {
             return fail("entity", sourceLocationFromNode(call, sourceFile), "object form requires a string-literal `name` property");
         }
-        const definition = readDataLiteralNode(obj);
+        const definition = readSpreadOnlyDefinition(obj) ?? readDataLiteralNode(obj);
         if (!isPlainObject(definition)) {
             return fail("entity", sourceLocationFromNode(call, sourceFile), "definition could not be read as a plain object (contains functions or identifiers)");
         }

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

@@ -202,15 +202,12 @@ function renderDescribe(p) {
     return `r.describe(${JSON.stringify(p.text)});`;
 }
 function renderEntity(p) {
-    // A whole-value raw-ref (`r.entity("x", eventEntity)`) can't be spread
-    // into the merged Object-Form without losing `name` to the sentinel
-    // shortcut in renderValue — fall back to the classic positional form,
-    // which keeps the reference verbatim alongside the name.
+    // A whole-value raw-ref (`eventEntity`) can't go through renderValue without
+    // losing `name` to the sentinel shortcut — spread the reference verbatim
+    // next to the name instead.
     if (isRawRefSentinel(p.definition)) {
-        return `r.entity(${JSON.stringify(p.entityName)}, ${p.definition.__raw});`;
+        return `r.entity({ name: ${JSON.stringify(p.entityName)}, ...${p.definition.__raw} });`;
     }
-    // Inline `name` into the definition object — canonical Object-Form
-    // is a single arg with name-as-property.
     const merged = { name: p.entityName, ...p.definition };
     return `r.entity(${renderValue(merged)});`;
 }

package/dist/engine/feature-config-events-jobs.d.ts

@@ -25,6 +25,7 @@ export declare function buildConfigEventsJobsMethods<TName extends string>(state
         readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
         readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
         readonly localizedTemplate?: () => NotificationLocalizedTemplate;
+        readonly renamedFrom?: readonly string[];
     }), definition?: {
         readonly trigger?: {
             readonly on: NameOrRef;
@@ -37,6 +38,7 @@ export declare function buildConfigEventsJobsMethods<TName extends string>(state
         readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
         readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
         readonly localizedTemplate?: () => NotificationLocalizedTemplate;
+        readonly renamedFrom?: readonly string[];
     }): void;
     translations(def: TranslationsDef): void;
     defineEvent: <const TInner extends string, TPayload>(eventName: TInner, schema: ZodType<TPayload>, options: {