@cosmicdrift/kumiko-samples 0.358.0 → 0.359.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.358.0",
+  "version": "0.359.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.358.0",
+  "version": "0.359.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/src/custom-fields/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.359.0",
+    "type": "improvement",
+    "title": "update-tenant-field keeps the stored type when serializedField.type is omitted",
+    "detail": "custom-fields: update-tenant-field accepts serializedField without type and keeps the stored type; a different type is still refused with 422 field_type_immutable. The handler declares excludedFields [\"type\"]."
+  },
   {
     "version": "0.338.0",
     "type": "fix",

package/packages/bundled-features/src/custom-fields/handlers/update-tenant-field.write.ts

@@ -4,32 +4,33 @@ import { fieldDefinitionAggregateId } from "../aggregate-id.js";
 import { DEFAULT_FIELD_DEFINITION_WRITE_ROLES } from "../constants.js";
 import { fieldDefinitionExecutor } from "../executor.js";
 import { buildFieldDefinitionColumns } from "../lib/field-definition-row.js";
-import { type UpdateFieldPayload, updateFieldPayloadSchema } from "../schemas.js";
+import { fieldTypeSchema, type UpdateFieldPayload, updateFieldPayloadSchema } from "../schemas.js";
 
-// update-tenant-field — TenantAdmin ersetzt den Stand einer bestehenden
-// Field-Definition (Vollersatz: Payload-Shape = define, der Edit-Screen
-// schickt den kompletten neuen Stand). Identität ist (entityName, fieldKey)
-// → deterministische aggregate-id wie bei define/delete; tenantId kommt
-// aus event.user (Cross-Tenant-Mutation unmöglich, fremde Definitionen
-// derivieren auf eine andere aggregate-id → 404).
+// update-tenant-field: a TenantAdmin replaces the state of an existing field
+// definition (full replacement: payload shape = define except that
+// `serializedField.type` may be omitted). Identity is (entityName, fieldKey),
+// giving the same deterministic aggregate id as define/delete; tenantId comes
+// from event.user, so a cross-tenant mutation is impossible (a foreign
+// definition derives a different aggregate id and yields 404).
 //
-// **type ist immutable.** Ein Type-Wechsel würde bestehende Values in den
-// host-entity customFields-jsonbs verwaisen (text-Wert unter number-Feld);
-// dafür ist delete + re-define der ehrliche Weg (Bug-Bash D2: bewusst KEIN
-// delete+redefine im update — das würde Event-Historie + Field-Ids
-// zerstören, aber ein Type-Wechsel will genau diese Zäsur).
+// **type is immutable**; an omitted type keeps the stored one. A type change
+// would orphan existing values in the host entities' customFields jsonb (a
+// text value under a number field), so delete + re-define is the honest path
+// (Bug-Bash D2: deliberately no delete+redefine inside update, since that
+// destroys event history and field ids, which is exactly the break a type
+// change needs to make visible).
 //
-// **Bekannte MVP-Grenze (bewusst):** der Edit reconciled bestehende
-// Host-Werte NICHT gegen die neue Definition — Constraint-Narrowing
-// (enum-Wert weg, min/max enger) lässt alte Werte still non-conformant,
-// required false→true macht Bestands-Rows unvollständig, searchable-Toggle
-// re-indexed nicht. Werte werden beim NÄCHSTEN Write der Host-Row gegen
-// die aktuelle Def validiert; eine Reject-mit-Konflikt-Liste-Variante
-// wäre der Ausbau, wenn der Bedarf real wird.
+// **Known MVP limit (deliberate):** the edit does NOT reconcile existing host
+// values against the new definition. Narrowed constraints (enum value removed,
+// tighter min/max) leave old values silently non-conformant, required
+// false→true leaves existing rows incomplete, and toggling searchable does not
+// re-index. Values are validated against the current definition on the NEXT
+// write of the host row; a reject-with-conflict-list variant is the upgrade
+// once the need is real.
 //
-// **skipOptimisticLock:** Definition-Edits sind admin-only + low-frequency
-// (gleiche Abwägung wie der Quota-soft-cap in define). Last-write-wins
-// statt version-Roundtrip durch den Edit-Screen.
+// **skipOptimisticLock:** definition edits are admin-only and low-frequency
+// (same trade-off as the quota soft cap in define), so last write wins instead
+// of a version round trip through the edit screen.
 export interface UpdateTenantFieldOptions {
   /** Access roles for this handler. Default ["TenantAdmin"] (#2296) — see
    *  DefineTenantFieldOptions.roles, the definition-CRUD triad shares one gate. */
@@ -44,7 +45,8 @@ export function createUpdateTenantFieldHandler(
     schema: updateFieldPayloadSchema,
     access: { roles: opts.roles ?? DEFAULT_FIELD_DEFINITION_WRITE_ROLES },
     description:
-      "Replaces a tenant-owned custom-field definition with a complete new spec while refusing any change to the field's type; use it to relabel or re-constrain an existing field rather than to create or remove one.",
+      "Replaces a tenant-owned custom-field definition with a complete new spec; serializedField.type may be omitted, in which case the stored type applies, and a different type is refused. Use it to relabel or re-constrain an existing field rather than to create or remove one.",
+    excludedFields: ["type"],
     handler: async (event, ctx) => {
       const payload = event.payload as UpdateFieldPayload; // @cast-boundary engine-payload
       const tenantId = event.user.tenantId;
@@ -70,12 +72,19 @@ export function createUpdateTenantFieldHandler(
         return failNotFound("field-definition", aggregateId);
       }
 
-      if (existing["type"] !== payload.serializedField.type) {
+      const storedType = fieldTypeSchema.safeParse(existing["type"]);
+      if (!storedType.success) {
+        throw new Error(
+          `update-tenant-field: stored definition ${aggregateId} has an invalid type`,
+        );
+      }
+      const requestedType = payload.serializedField.type;
+      if (requestedType !== undefined && requestedType !== storedType.data) {
         return failUnprocessable("field_type_immutable", {
           entityName: payload.entityName,
           fieldKey: payload.fieldKey,
-          currentType: existing["type"],
-          requestedType: payload.serializedField.type,
+          currentType: storedType.data,
+          requestedType,
         });
       }
 
@@ -84,7 +93,10 @@ export function createUpdateTenantFieldHandler(
         entityName: _entityName,
         fieldKey: _fieldKey,
         ...changes
-      } = buildFieldDefinitionColumns(payload);
+      } = buildFieldDefinitionColumns({
+        ...payload,
+        serializedField: { ...payload.serializedField, type: storedType.data },
+      });
 
       return fieldDefinitionExecutor.update({ id: aggregateId, changes }, event.user, ctx.db, {
         skipOptimisticLock: true,

package/packages/bundled-features/src/custom-fields/schemas.ts

@@ -2,7 +2,7 @@ import * as z from "zod";
 import { SUPPORTED_FIELD_TYPES } from "./constants.js";
 
 // Field-Type-Validator — pinnt valid type-Werte für fieldDefinition.
-const fieldTypeSchema = z.enum(SUPPORTED_FIELD_TYPES);
+export const fieldTypeSchema = z.enum(SUPPORTED_FIELD_TYPES);
 
 // Per-field access-control. When set, `set/clear-custom-field` handlers
 // require the calling user to hold at least one of the listed roles —
@@ -37,29 +37,37 @@ export type CustomFieldAccess = z.infer<typeof customFieldAccessSchema>;
 // Everything else stays loose pending B2's per-type discriminated-union —
 // EXCEPT `sensitive`, which is explicitly rejected below: custom fields
 // carry supplemental business data only, PII support was removed (#972).
+const serializedFieldBaseShape = {
+  fieldAccess: customFieldAccessSchema,
+  // `retention` (T1.5d): per-field expiry. The retention-cron strips
+  // values whose host-row `modified_at` is older than `keepFor`. Strategy
+  // `delete` removes the key from the customFields jsonb; `anonymize`
+  // sets it to `null` (key stays, value gone — preserves the schema
+  // shape for downstream consumers).
+  retention: z
+    .object({
+      keepFor: z
+        .string()
+        .regex(/^\d+[hdwmy]$/, "keepFor must match /^\\d+[hdwmy]$/ (e.g. '30d', '10y')"),
+      strategy: z.enum(["delete", "anonymize"]),
+    })
+    .optional(),
+};
+
+const rejectSensitive = [
+  (v: Record<string, unknown>) => !("sensitive" in v),
+  "custom fields don't support PII — `sensitive` was removed (#972). Model personal data as a schema entity field with a pii/userOwned/tenantOwned annotation instead.",
+] as const;
+
 const serializedFieldSchema = z
-  .looseObject({
-    type: fieldTypeSchema,
-    fieldAccess: customFieldAccessSchema,
-    // `retention` (T1.5d): per-field expiry. The retention-cron strips
-    // values whose host-row `modified_at` is older than `keepFor`. Strategy
-    // `delete` removes the key from the customFields jsonb; `anonymize`
-    // sets it to `null` (key stays, value gone — preserves the schema
-    // shape for downstream consumers).
-    retention: z
-      .object({
-        keepFor: z
-          .string()
-          .regex(/^\d+[hdwmy]$/, "keepFor must match /^\\d+[hdwmy]$/ (e.g. '30d', '10y')"),
-        strategy: z.enum(["delete", "anonymize"]),
-      })
-      .optional(),
-  })
+  .looseObject({ type: fieldTypeSchema, ...serializedFieldBaseShape })
   .refine((v) => typeof v["type"] === "string", "serializedField must have a string `type`")
-  .refine(
-    (v) => !("sensitive" in v),
-    "custom fields don't support PII — `sensitive` was removed (#972). Model personal data as a schema entity field with a pii/userOwned/tenantOwned annotation instead.",
-  );
+  .refine(...rejectSensitive);
+
+// Update may omit `type`: it is immutable, so the handler takes it from the stored definition.
+const updateSerializedFieldSchema = z
+  .looseObject({ type: fieldTypeSchema.optional(), ...serializedFieldBaseShape })
+  .refine(...rejectSensitive);
 
 // i18n-labels — `{ de: "...", en: "...", ... }`. Mindestens ein Eintrag.
 const labelSchema = z.record(z.string().min(2).max(8), z.string().min(1));
@@ -83,12 +91,14 @@ export const defineFieldPayloadSchema = z.object({
 });
 export type DefineFieldPayload = z.infer<typeof defineFieldPayloadSchema>;
 
-// Payload für `update-tenant-field` — bewusst dieselbe Shape wie define
-// (Vollersatz-Semantik: der Edit-Screen schickt den kompletten neuen Stand;
-// entityName+fieldKey sind die Identität, type ist immutable und wird im
-// Handler gegen den Bestand geprüft).
-export const updateFieldPayloadSchema = defineFieldPayloadSchema;
-export type UpdateFieldPayload = DefineFieldPayload;
+// Payload for `update-tenant-field`: full replacement like define (the edit
+// screen sends the complete new state; entityName+fieldKey are the identity),
+// except that `serializedField.type` may be omitted. type is immutable; a
+// differing value is refused in the handler.
+export const updateFieldPayloadSchema = defineFieldPayloadSchema.extend({
+  serializedField: updateSerializedFieldSchema,
+});
+export type UpdateFieldPayload = z.infer<typeof updateFieldPayloadSchema>;
 
 // Payload für `delete-tenant-field` / `delete-system-field`.
 export const deleteFieldPayloadSchema = z.object({