@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/dist/engine/factories.d.ts

@@ -0,0 +1,195 @@
+import type { EntityTenancy } from "@cosmicdrift/kumiko-types/tenancy-brand";
+import type { BigIntFieldDef, BooleanFieldDef, DateFieldDef, DecimalFieldDef, DerivedFieldDef, EmbeddedFieldDef, EntityDefinition, EntityIndexDef, FieldsMap, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, ResolvedPiiFlags, RetentionDef, SelectFieldDef, TextFieldDef, TimestampFieldDef, TzFieldDef } from "./types/index.js";
+export declare function createTextField<R extends true | false = false>(overrides: Partial<Omit<TextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotations & {
+    required?: R;
+}): TextFieldDef & {
+    required: R;
+};
+/**
+ * Long-form text field for source-code, markdown, blog-posts, email-
+ * templates — anything that can be megabytes large. Type-level differs
+ * from `text`: keine sortable/searchable/filterable/format options.
+ * DB-mapping ist identisch zu text (PG text ist unbounded).
+ *
+ * Soft-cap default: kein maxLength (PG text ist 1 GB hart begrenzt).
+ * Setze einen explicit `maxLength` wenn du ein verirrtes Browser-Paste
+ * früh ablehnen willst (z.B. 1_000_000 = 1 MB).
+ */
+/**
+ * Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`).
+ * The value is derived per row from the stored columns + the clock at query
+ * time, never persisted. Display only — server-side sort/filter/search don't
+ * apply and there's no client-side sort path (see DerivedFieldDef). `derive`
+ * must take its clock from `ctx.asOf`, never `Temporal.Now`/`Date`.
+ */
+export declare function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef;
+export declare function createLongTextField<R extends true | false = false>(overrides: Partial<Omit<LongTextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsLongText & {
+    required?: R;
+}): LongTextFieldDef & {
+    required: R;
+};
+export declare function createBooleanField<R extends true | false = false>(overrides?: Partial<Omit<BooleanFieldDef, "type" | "required">> & {
+    required?: R;
+}): BooleanFieldDef & {
+    required: R;
+};
+export declare function createSelectField<const TOptions extends readonly string[], R extends true | false = false>(opts: {
+    options: TOptions;
+} & Partial<Omit<SelectFieldDef<TOptions>, "type" | "options" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
+    required?: R;
+}): SelectFieldDef<TOptions> & {
+    required: R;
+};
+/**
+ * Multi-select field — N values from a fixed option list.
+ *
+ * Storage: jsonb-Array<string>. Every entry must be in `options`
+ * (boot-validator). Renders as a combobox dropdown by default; set
+ * `display: "checkboxes"` to render every option as a visible checkbox with
+ * a select-all toggle instead.
+ *
+ * ```ts
+ * licenceClasses: createMultiSelectField({
+ *   options: ["B", "BE", "C", "C1", "CE", "C1E", "D", "D1"] as const,
+ *   default: ["B"],
+ * }),
+ *
+ * languages: createMultiSelectField({
+ *   options: ["en", "de", "es", "fr", "it"] as const,
+ *   display: "checkboxes",
+ *   columns: 2,
+ * }),
+ * ```
+ *
+ * Caller-API:
+ *   Write: `{ licenceClasses: ["B", "BE", "C1"] }`
+ *   Read:  `{ licenceClasses: ["B", "BE", "C1"] }`
+ *
+ * Use instead of `select` when more than one value can be chosen at once.
+ * Use instead of `embedded` with booleans once there are more than ~5 options.
+ */
+export declare function createMultiSelectField<const TOptions extends readonly string[]>(opts: {
+    options: TOptions;
+} & Partial<Omit<MultiSelectFieldDef<TOptions>, "type" | "options" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): MultiSelectFieldDef<TOptions>;
+/**
+ * Numeric field — `double precision` column by default (fractional values
+ * allowed end to end). Pass `integer: true` for a 32-bit `integer` column
+ * with `.int()` write-boundary validation. Need exact decimal storage
+ * instead (money-adjacent math)? Use `createDecimalField` (`numeric`).
+ */
+export declare function createNumberField<R extends true | false = false>(overrides?: Partial<Omit<NumberFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
+    required?: R;
+}): NumberFieldDef & {
+    required: R;
+};
+export declare function createBigIntField<R extends true | false = false>(overrides?: Partial<Omit<BigIntFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
+    required?: R;
+}): BigIntFieldDef & {
+    required: R;
+};
+export declare function createDecimalField<R extends true | false = false>(config: {
+    precision: number;
+    scale: number;
+} & Partial<Omit<DecimalFieldDef, "type" | "precision" | "scale" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
+    required?: R;
+}): DecimalFieldDef & {
+    required: R;
+};
+export declare function createMoneyField<R extends true | false = false>(overrides?: Partial<Omit<MoneyFieldDef, "type" | "required">> & {
+    required?: R;
+}): MoneyFieldDef & {
+    required: R;
+};
+export declare function createEmbeddedField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef;
+export declare function createEmbeddedListField(schema: EmbeddedFieldDef["schema"], overrides?: Partial<Omit<EmbeddedFieldDef, "type" | "schema" | "multiple" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): EmbeddedFieldDef & {
+    multiple: true;
+};
+export declare function createJsonbField(overrides?: Partial<Omit<JsonbFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): JsonbFieldDef;
+export declare function createDateField<R extends true | false = false>(overrides?: Partial<Omit<DateFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
+    required?: R;
+}): DateFieldDef & {
+    required: R;
+};
+/**
+ * UTC-Instant — für Ereignisse die zu einem bestimmten Zeitpunkt passieren
+ * (createdAt, loginAt, actualPickupAt). Temporal.Instant intern.
+ *
+ * Mit `locatedBy: "<name>Tz"` wird das Feld zum Wall-Clock-Pair eines
+ * Termins an einem Ort — bevorzuge dafür `createLocatedTimestampField()`,
+ * das EIN atomares Feld statt eines lose verdrahteten Pairs erzeugt.
+ */
+export declare function createTimestampField<R extends true | false = false>(overrides?: Partial<Omit<TimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
+    required?: R;
+}): TimestampFieldDef & {
+    required: R;
+};
+/**
+ * IANA-Zonenname (z.B. "Europe/Berlin"). Wird im Boot/Schema-Validator
+ * via `Intl.supportedValuesOf("timeZone")` geprüft (kommt im Zod-Schritt).
+ */
+export declare function createTzField<R extends true | false = false>(overrides?: Partial<Omit<TzFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
+    required?: R;
+}): TzFieldDef & {
+    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).
+ *
+ * EIN Schema-Feld → ZWEI DB-Spalten (`<name>_utc TIMESTAMPTZ` + `<name>_tz TEXT`)
+ * → DREI API-Felder beim Read (`{ at, tz, utc }`).
+ *
+ * ```ts
+ * r.entity("order", {
+ *   fields: {
+ *     pickup: createLocatedTimestampField(),
+ *     delivery: createLocatedTimestampField(),
+ *   },
+ * });
+ *
+ * // Write — Caller schickt at+tz, Framework rechnet utc aus
+ * await create({ pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" } });
+ *
+ * // Read — Framework liefert alle drei Felder zurück
+ * // → { pickup: { at: "10:00", tz: "Europe/Lisbon", utc: "09:00Z" } }
+ *
+ * // Sort/Filter über die UTC-Spalte
+ * 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.
+ */
+export declare function createLocatedTimestampField<R extends true | false = false>(overrides?: Partial<Omit<LocatedTimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
+    required?: R;
+}): LocatedTimestampFieldDef & {
+    required: R;
+};
+export declare function createFileField(overrides?: Partial<Omit<FileFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FileFieldDef;
+export declare function createImageField(overrides?: Partial<Omit<ImageFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): ImageFieldDef;
+export declare function createFilesField(overrides?: Partial<Omit<FilesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): FilesFieldDef;
+export declare function createImagesField(overrides?: Partial<Omit<ImagesFieldDef, "type" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind): ImagesFieldDef;
+export declare function createEntity<F, const T extends EntityTenancy = "tenant">(def: {
+    readonly table?: string;
+    readonly fields: F;
+    readonly description?: string;
+    readonly softDelete?: boolean;
+    /** Event stream lives on SYSTEM_TENANT_ID (tenant-independent aggregate, e.g.
+     *  user) instead of the creator's tenant. See EntityDefinition.systemStream. */
+    readonly systemStream?: boolean;
+    readonly searchWeight?: number;
+    readonly defaultCurrency?: string;
+    readonly transitions?: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
+    readonly indexes?: readonly EntityIndexDef[];
+    readonly idType?: "serial" | "uuid";
+    readonly access?: EntityDefinition["access"];
+    /** Join-row carrier reference — see EntityDefinition.parentRef. */
+    readonly parentRef?: EntityDefinition["parentRef"];
+    readonly retention?: RetentionDef;
+    readonly derivedFields?: EntityDefinition["derivedFields"];
+    readonly tenancy?: T;
+    /** See EntityDefinition.transferable. */
+    readonly transferable?: boolean;
+}): F extends FieldsMap ? EntityDefinition<F, T> : never;

package/dist/engine/factories.js

@@ -0,0 +1,387 @@
+// `personal: { of: "id" }` means the row itself is the subject, not a
+// referenced user — resolves to `recordOwned` instead of `userOwned`.
+const RECORD_OWNER_FIELD = "id";
+// Resolves the author-facing `personal`/`find` annotations (kumiko-framework#2250)
+// into the internal ResolvedPiiFlags every factory below merges into its
+// return value. `personal`, `find`, `reason` never survive into the field def.
+function expandPersonalAnnotations(overrides) {
+    if (!overrides) {
+        return {};
+    }
+    const { personal, find, reason, anonymize, ...rest } = overrides;
+    let personalFlags = {};
+    if (personal === "self") {
+        personalFlags = { pii: true };
+    }
+    else if (personal === "tenant") {
+        personalFlags = { tenantOwned: true };
+    }
+    else if (personal === "ref") {
+        personalFlags = { subjectRef: true };
+    }
+    else if (personal === false) {
+        personalFlags = { allowPlaintext: reason };
+    }
+    else if (personal && personal.of === RECORD_OWNER_FIELD) {
+        personalFlags = { recordOwned: true };
+    }
+    else if (personal) {
+        personalFlags = { userOwned: { ownerField: personal.of } };
+    }
+    // `searchable`/`sensitive` live on the individual FieldDef, not on
+    // ResolvedPiiFlags — "fuzzy"/"secret" resolve into those too.
+    let findFlags = {};
+    if (find === "exact") {
+        findFlags = { lookupable: true };
+    }
+    else if (find === "fuzzy") {
+        findFlags = { lookupable: true, searchable: true };
+    }
+    else if (find === "secret") {
+        findFlags = { sensitive: true };
+    }
+    return {
+        ...rest,
+        ...personalFlags,
+        ...findFlags,
+        ...(anonymize ? { anonymize } : {}),
+    };
+}
+// `find` is mandatory once a subject is named (types require it — see
+// PersonalAnnotations / PersonalAnnotationsLongText), but the valid values
+// differ per factory: longText has no lookup/search machinery.
+const TEXT_FIELD_STANCE_FIND_VALUES = {
+    createTextField: ["exact", "fuzzy", "none", "secret"],
+    createLongTextField: ["none", "secret"],
+};
+function textFieldStanceHint(factoryName) {
+    const find = TEXT_FIELD_STANCE_FIND_VALUES[factoryName].map((f) => `"${f}"`).join(" | ");
+    return (`{ personal: "self", find: ${find} }, ` +
+        `{ personal: "tenant", find: ${find} }, ` +
+        `{ personal: { of: "<ownerField>" }, find: ${find} }, ` +
+        `{ personal: "ref" }, or ` +
+        `{ personal: false, reason: "<why this is not personal data>" }`);
+}
+function missingTextFieldStanceError(factoryName) {
+    return new Error(`${factoryName}(...) must declare an explicit personal-data stance — a text field must state whose data it holds and (unless it isn't personal data) how findable it needs to stay (kumiko-framework#2921). Pass one of: ${textFieldStanceHint(factoryName)}. Run \`kumiko-guards guards --guard="Text-Field Personal-Stance Guard"\` to find remaining call sites.`);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+// Fail-closed stance gate (kumiko-framework#2921) for the two text-shaped
+// factories — runs before expandPersonalAnnotations so an untyped JS caller
+// (no compiler to stop it) can't slip an unannotated text field past the
+// type layer either. `overrides` is `unknown` here on purpose: the typed
+// signature above already rejects a missing/malformed shape at compile
+// time, this re-checks the same shape at the runtime boundary.
+function assertTextFieldStance(factoryName, overrides) {
+    if (overrides === null || typeof overrides !== "object") {
+        throw missingTextFieldStanceError(factoryName);
+    }
+    // @cast-boundary runtime-guard — re-validated field by field below before
+    // any value is trusted.
+    const { personal, find, reason } = overrides;
+    if (personal === undefined || personal === null) {
+        throw missingTextFieldStanceError(factoryName);
+    }
+    if (personal === "ref") {
+        // skip: a user reference carries no content of its own, so no `find` applies
+        return;
+    }
+    if (personal === false) {
+        if (!isNonEmptyString(reason)) {
+            throw missingTextFieldStanceError(factoryName);
+        }
+        // skip: plaintext by declaration, `find` only applies to a named subject
+        return;
+    }
+    const hasValidSubject = personal === "self" ||
+        personal === "tenant" ||
+        (typeof personal === "object" && isNonEmptyString(personal.of));
+    if (!hasValidSubject) {
+        throw missingTextFieldStanceError(factoryName);
+    }
+    const validFinds = TEXT_FIELD_STANCE_FIND_VALUES[factoryName];
+    if (typeof find !== "string" || !validFinds.includes(find)) {
+        throw missingTextFieldStanceError(factoryName);
+    }
+}
+// Generic über `R extends true | false` (statt `boolean`) damit
+// `createTextField({ required: true })` literal `required: true` im
+// Return-Type behält. `boolean` würde widenen — EntityTable<E>'s
+// Mapped-Type könnte dann nicht zwischen `required: true` und
+// `required: false` dispatchen, jede Column würde zu nullable
+// degradieren. Default `R = false` matcht den runtime-default. Pattern
+// in jeder required-bearing factory unten.
+export function createTextField(overrides) {
+    assertTextFieldStance("createTextField", overrides);
+    return {
+        type: "text",
+        maxLength: 200,
+        required: false,
+        searchable: false,
+        sortable: false,
+        ...expandPersonalAnnotations(overrides),
+    }; // @cast-boundary engine-payload
+}
+/**
+ * Long-form text field for source-code, markdown, blog-posts, email-
+ * templates — anything that can be megabytes large. Type-level differs
+ * from `text`: keine sortable/searchable/filterable/format options.
+ * DB-mapping ist identisch zu text (PG text ist unbounded).
+ *
+ * Soft-cap default: kein maxLength (PG text ist 1 GB hart begrenzt).
+ * Setze einen explicit `maxLength` wenn du ein verirrtes Browser-Paste
+ * früh ablehnen willst (z.B. 1_000_000 = 1 MB).
+ */
+/**
+ * Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`).
+ * The value is derived per row from the stored columns + the clock at query
+ * time, never persisted. Display only — server-side sort/filter/search don't
+ * apply and there's no client-side sort path (see DerivedFieldDef). `derive`
+ * must take its clock from `ctx.asOf`, never `Temporal.Now`/`Date`.
+ */
+export function createDerivedField(spec) {
+    return { ...spec };
+}
+export function createLongTextField(overrides) {
+    assertTextFieldStance("createLongTextField", overrides);
+    return {
+        type: "longText",
+        required: false,
+        ...expandPersonalAnnotations(overrides),
+    }; // @cast-boundary engine-payload
+}
+export function createBooleanField(overrides) {
+    return {
+        type: "boolean",
+        required: false,
+        default: false,
+        ...overrides,
+    }; // @cast-boundary engine-payload
+}
+export function createSelectField(opts) {
+    return {
+        type: "select",
+        required: false,
+        ...expandPersonalAnnotations(opts),
+    }; // @cast-boundary engine-payload
+}
+/**
+ * Multi-select field — N values from a fixed option list.
+ *
+ * Storage: jsonb-Array<string>. Every entry must be in `options`
+ * (boot-validator). Renders as a combobox dropdown by default; set
+ * `display: "checkboxes"` to render every option as a visible checkbox with
+ * a select-all toggle instead.
+ *
+ * ```ts
+ * licenceClasses: createMultiSelectField({
+ *   options: ["B", "BE", "C", "C1", "CE", "C1E", "D", "D1"] as const,
+ *   default: ["B"],
+ * }),
+ *
+ * languages: createMultiSelectField({
+ *   options: ["en", "de", "es", "fr", "it"] as const,
+ *   display: "checkboxes",
+ *   columns: 2,
+ * }),
+ * ```
+ *
+ * Caller-API:
+ *   Write: `{ licenceClasses: ["B", "BE", "C1"] }`
+ *   Read:  `{ licenceClasses: ["B", "BE", "C1"] }`
+ *
+ * Use instead of `select` when more than one value can be chosen at once.
+ * Use instead of `embedded` with booleans once there are more than ~5 options.
+ */
+export function createMultiSelectField(opts) {
+    return {
+        type: "multiSelect",
+        required: false,
+        ...expandPersonalAnnotations(opts),
+    };
+}
+/**
+ * Numeric field — `double precision` column by default (fractional values
+ * allowed end to end). Pass `integer: true` for a 32-bit `integer` column
+ * with `.int()` write-boundary validation. Need exact decimal storage
+ * instead (money-adjacent math)? Use `createDecimalField` (`numeric`).
+ */
+export function createNumberField(overrides) {
+    return {
+        type: "number",
+        required: false,
+        ...expandPersonalAnnotations(overrides),
+    }; // @cast-boundary engine-payload
+}
+export function createBigIntField(overrides) {
+    return {
+        type: "bigInt",
+        required: false,
+        ...expandPersonalAnnotations(overrides),
+    }; // @cast-boundary engine-payload
+}
+// Exact decimal column — numeric(precision, scale). precision/scale are
+// required (no truncating default). See DecimalFieldDef for the precision
+// caveat (surfaced as JS number, safe ≤ 2^53).
+export function createDecimalField(config) {
+    // Fail at definition time, not at the first migration: numeric(p,s) requires
+    // integer p ≥ 1 and 0 ≤ s ≤ p (Postgres rejects e.g. numeric(2,4), and the
+    // schema-builder's `10 ** (precision - scale)` bound goes nonsensical).
+    const { precision, scale } = config;
+    if (!Number.isInteger(precision) ||
+        !Number.isInteger(scale) ||
+        precision < 1 ||
+        scale < 0 ||
+        scale > precision) {
+        throw new Error(`createDecimalField: precision/scale must be integers with precision ≥ 1 and ` +
+            `0 ≤ scale ≤ precision, got precision=${precision}, scale=${scale}`);
+    }
+    return {
+        type: "decimal",
+        required: false,
+        ...expandPersonalAnnotations(config),
+    }; // @cast-boundary engine-payload
+}
+export function createMoneyField(overrides) {
+    return {
+        type: "money",
+        ...overrides,
+    }; // @cast-boundary engine-payload
+}
+export function createEmbeddedField(schema, overrides) {
+    return {
+        type: "embedded",
+        schema,
+        ...expandPersonalAnnotations(overrides),
+    };
+}
+// A list of like-shaped objects — see `EmbeddedFieldDef.multiple` for when an
+// embedded list is the right model and when the rows belong in their own
+// entity. `required: true` means the insert must carry the key AND at least
+// one row (analogous to multiSelect); the column itself is never null, it
+// defaults to `[]`.
+//
+// The `multiple: true` literal is part of the return type because the
+// table-builder's ColumnsForField branches on it — a widened `boolean` would
+// silently fall back to the single-object column type.
+export function createEmbeddedListField(schema, overrides) {
+    return {
+        type: "embedded",
+        schema,
+        ...expandPersonalAnnotations(overrides),
+        multiple: true,
+    };
+}
+// Free-form jsonb-Spalte — siehe `JsonbFieldDef`-Doku. Schema-less, default
+// `{}`, NOT NULL. Hauptnutzer: custom-fields-Bundle (host-entity's
+// `customFields`-Spalte). Andere valid uses: tenant-config-blobs, AI-
+// inferred-metadata, future tags-arrays.
+export function createJsonbField(overrides) {
+    return {
+        type: "jsonb",
+        ...expandPersonalAnnotations(overrides),
+    };
+}
+export function createDateField(overrides) {
+    return {
+        type: "date",
+        required: false,
+        ...expandPersonalAnnotations(overrides),
+    }; // @cast-boundary engine-payload
+}
+/**
+ * UTC-Instant — für Ereignisse die zu einem bestimmten Zeitpunkt passieren
+ * (createdAt, loginAt, actualPickupAt). Temporal.Instant intern.
+ *
+ * Mit `locatedBy: "<name>Tz"` wird das Feld zum Wall-Clock-Pair eines
+ * Termins an einem Ort — bevorzuge dafür `createLocatedTimestampField()`,
+ * das EIN atomares Feld statt eines lose verdrahteten Pairs erzeugt.
+ */
+export function createTimestampField(overrides) {
+    // Object-Build vermeidet hartcodiertes `required: false` im literal —
+    // das würde TS dazu bringen, R auf `boolean` zu widenen statt das
+    // literal `true`/`false` aus dem overrides-Argument zu inferieren.
+    return {
+        ...expandPersonalAnnotations(overrides),
+        type: "timestamp",
+        required: (overrides?.required ?? false), // @cast-boundary engine-payload
+    };
+}
+/**
+ * IANA-Zonenname (z.B. "Europe/Berlin"). Wird im Boot/Schema-Validator
+ * via `Intl.supportedValuesOf("timeZone")` geprüft (kommt im Zod-Schritt).
+ */
+export function createTzField(overrides) {
+    return {
+        type: "tz",
+        required: false,
+        ...expandPersonalAnnotations(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).
+ *
+ * EIN Schema-Feld → ZWEI DB-Spalten (`<name>_utc TIMESTAMPTZ` + `<name>_tz TEXT`)
+ * → DREI API-Felder beim Read (`{ at, tz, utc }`).
+ *
+ * ```ts
+ * r.entity("order", {
+ *   fields: {
+ *     pickup: createLocatedTimestampField(),
+ *     delivery: createLocatedTimestampField(),
+ *   },
+ * });
+ *
+ * // Write — Caller schickt at+tz, Framework rechnet utc aus
+ * await create({ pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" } });
+ *
+ * // Read — Framework liefert alle drei Felder zurück
+ * // → { pickup: { at: "10:00", tz: "Europe/Lisbon", utc: "09:00Z" } }
+ *
+ * // Sort/Filter über die UTC-Spalte
+ * 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.
+ */
+export function createLocatedTimestampField(overrides) {
+    return {
+        type: "locatedTimestamp",
+        required: false,
+        ...expandPersonalAnnotations(overrides),
+    }; // @cast-boundary engine-payload
+}
+export function createFileField(overrides) {
+    return { type: "file", ...expandPersonalAnnotations(overrides) };
+}
+export function createImageField(overrides) {
+    return { type: "image", ...expandPersonalAnnotations(overrides) };
+}
+export function createFilesField(overrides) {
+    return { type: "files", ...expandPersonalAnnotations(overrides) };
+}
+export function createImagesField(overrides) {
+    return { type: "images", ...expandPersonalAnnotations(overrides) };
+}
+// `F` läuft OHNE Constraint im Generic-Param damit TS die literal-types
+// einzelner Field-Defs durchzieht (required: true bleibt true, nicht
+// boolean). Constraint-Match gegen FieldsMap würde widenen — siehe TS-
+// Issue um Constraint-Inferenz auf strukturellen Records. Stattdessen
+// validieren wir die Conformance via conditional return type: wenn F
+// nicht FieldsMap-compat ist, kollabiert der Return zu `never`.
+export function createEntity(def) {
+    return {
+        softDelete: false,
+        searchWeight: 1,
+        // Default to UUID — post-ES-pivot every entity is event-sourced and
+        // aggregate-ids are UUID. Opt-out with `idType: "serial"` for pre-ES
+        // legacy tables (should be rare).
+        ...def,
+    }; // @cast-boundary engine-payload
+}

package/dist/engine/feature-ast/entity-field-types.d.ts

@@ -0,0 +1,13 @@
+export type UnknownEntityFieldType = {
+    readonly fieldName: string;
+    readonly type: string;
+};
+/**
+ * Scans `definition.fields.<name>.type` for values outside the FieldDefinition
+ * catalogue. Tolerant of RawRefSentinel at every level (definition itself,
+ * `fields`, a single field, or its `type`) — those are unresolvable source
+ * references, not validated field shapes, and readDataLiteralNode already
+ * chose not to fail the whole extraction over them.
+ */
+export declare function findUnknownEntityFieldTypes(definition: unknown): readonly UnknownEntityFieldType[];
+export declare function describeUnknownFieldType(entry: UnknownEntityFieldType): string;

package/dist/engine/feature-ast/entity-field-types.js

@@ -0,0 +1,35 @@
+// Shared field-type validation for EntityDefinition. Used by both the
+// static extractor (extractEntity, parse-time ParseError) and the runtime
+// PatternChange validator (pattern-change-schema.ts) so the two never drift
+// into reporting different "unknown field type" catalogues (#3137).
+import { FIELD_TYPE_NAMES } from "@cosmicdrift/kumiko-types/fields";
+import { isPlainObject, isRawRefSentinel } from "./extractors/shared.js";
+/**
+ * Scans `definition.fields.<name>.type` for values outside the FieldDefinition
+ * catalogue. Tolerant of RawRefSentinel at every level (definition itself,
+ * `fields`, a single field, or its `type`) — those are unresolvable source
+ * references, not validated field shapes, and readDataLiteralNode already
+ * chose not to fail the whole extraction over them.
+ */
+export function findUnknownEntityFieldTypes(definition) {
+    if (isRawRefSentinel(definition) || !isPlainObject(definition))
+        return [];
+    const fields = definition["fields"];
+    if (isRawRefSentinel(fields) || !isPlainObject(fields))
+        return [];
+    const out = [];
+    for (const [fieldName, fieldDef] of Object.entries(fields)) {
+        if (isRawRefSentinel(fieldDef) || !isPlainObject(fieldDef))
+            continue;
+        const type = fieldDef["type"];
+        if (isRawRefSentinel(type) || typeof type !== "string")
+            continue;
+        if (!FIELD_TYPE_NAMES.includes(type)) {
+            out.push({ fieldName, type });
+        }
+    }
+    return out;
+}
+export function describeUnknownFieldType(entry) {
+    return `unknown field type "${entry.type}"; expected one of: ${FIELD_TYPE_NAMES.join(", ")}`;
+}

package/dist/engine/feature-ast/extractors/ai-steps.d.ts

@@ -0,0 +1,6 @@
+import type { CallExpression, SourceFile } from "ts-morph";
+import type { AiClassifyPattern, AiExtractPattern, AiGeneratePattern } from "../patterns.js";
+import { type ExtractOutput } from "./shared.js";
+export declare function extractAiGenerate(call: CallExpression, sourceFile: SourceFile): ExtractOutput<AiGeneratePattern>;
+export declare function extractAiExtract(call: CallExpression, sourceFile: SourceFile): ExtractOutput<AiExtractPattern>;
+export declare function extractAiClassify(call: CallExpression, sourceFile: SourceFile): ExtractOutput<AiClassifyPattern>;