@cosmicdrift/kumiko-framework 0.249.0 → 0.250.0

package/src/db/event-store-executor-read.ts

@@ -300,6 +300,69 @@ async function resolveReferenceMatches(
   return { ownColumn: descriptor.ownColumn, ids: rows.map((r) => r.id) };
 }
 
+// Projected alongside the row when a reference sort is active, so the keyset
+// cursor carries the label that was ordered by instead of the FK's UUID.
+const SORT_LABEL_ALIAS = "__kumiko_sort_label";
+
+// fw#2741 — resolve a `sortable: true` reference field's label inline for
+// ORDER BY. A correlated scalar subquery, not a join: the result set keeps one
+// row per entity row, the read model stays untouched, and the lookup rides the
+// target's primary key. Tenant-scoped exactly like the search path — a foreign
+// tenant's label must never influence this tenant's ordering.
+// undefined means "cannot order by this label", which drops the sort to plain
+// id order; falling back to the UUID column would look deliberate to the user
+// while being arbitrary, which the issue calls worse than no sorting.
+function buildReferenceSortExpr(
+  outerTableName: string,
+  ownColumnSql: string,
+  descriptor: { readonly targetEntityName: string; readonly labelField: string },
+  resolveEntity: (entityName: string) => EntityDefinition | undefined,
+  db: TenantDb,
+): ((params: unknown[]) => string) | undefined {
+  const targetEntity = resolveEntity(descriptor.targetEntityName);
+  if (targetEntity === undefined) {
+    // skip: unknown target entity — registry inconsistency the boot-validator
+    // should have caught; drop the sort rather than 500 the request
+    return undefined;
+  }
+  if (targetEntity.fields[descriptor.labelField] === undefined) {
+    // skip: labelField isn't a real (declared) column on the target entity
+    return undefined;
+  }
+  if (
+    collectEncryptedFieldNames(targetEntity).has(descriptor.labelField) ||
+    collectPiiSubjectFields(targetEntity).includes(descriptor.labelField)
+  ) {
+    // skip: encrypted/PII labelField — ciphertext orders by its bytes, which is
+    // arbitrary to the reader and would also rank rows by their stored secret
+    return undefined;
+  }
+
+  const targetTable = buildEntityTable(descriptor.targetEntityName, targetEntity);
+  const targetTableName = String(
+    (targetTable as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL],
+  );
+  const labelCol = physicalColumnName(targetTable, descriptor.labelField);
+  const tenantScoped = targetTable["tenantId"] !== undefined && db.mode === "tenant";
+  const tenantCol = tenantScoped ? physicalColumnName(targetTable, "tenantId") : "";
+  const tenantId = db.mode === "tenant" ? db.tenantId : undefined;
+
+  // No ::text cast (unlike the ILIKE search path): a non-text label must keep
+  // its native collation/numeric order, and the keyset param infers its type
+  // from the comparison anyway.
+  return (params: unknown[]): string => {
+    let tenantClause = "";
+    if (tenantScoped) {
+      params.push(tenantId, SYSTEM_TENANT_ID);
+      tenantClause = ` AND t."${tenantCol}" IN ($${params.length - 1}, $${params.length})`;
+    }
+    return (
+      `(SELECT t."${labelCol}" FROM "${targetTableName}" t ` +
+      `WHERE t."id" = "${outerTableName}".${ownColumnSql}${tenantClause})`
+    );
+  };
+}
+
 export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor, "list" | "detail"> {
   const {
     table,
@@ -431,12 +494,35 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
         whereSql.push(`(${orParts.join(" OR ")})`);
       }
 
-      const sortField =
+      const sortCandidate =
         payload.sort && table[payload.sort] && fieldReadClause(payload.sort).kind === "pass"
           ? payload.sort
           : undefined;
       const sortDescending = payload.sortDirection === "desc";
 
+      // fw#2741 — a reference column stores a UUID, so it is never sorted by
+      // directly: either the field opted into `sortable` and we order by the
+      // target row's label, or the sort is dropped to plain id order.
+      let sortField: string | undefined;
+      let referenceSortExpr: ((params: unknown[]) => string) | undefined;
+      if (sortCandidate !== undefined && entity.fields[sortCandidate]?.type === "reference") {
+        const referenceSort = runtimeOptions?.referenceSort;
+        const descriptor = referenceSort?.fields.find((f) => f.fieldName === sortCandidate);
+        referenceSortExpr =
+          referenceSort && descriptor
+            ? buildReferenceSortExpr(
+                tableName,
+                colSql(sortCandidate),
+                descriptor,
+                referenceSort.resolveEntity,
+                db,
+              )
+            : undefined;
+        if (referenceSortExpr !== undefined) sortField = sortCandidate;
+      } else {
+        sortField = sortCandidate;
+      }
+
       // Tenant-Filter (replicates TenantDb's readWhere semantics).
       if (table["tenantId"] !== undefined && db.mode === "tenant") {
         params.push(db.tenantId, SYSTEM_TENANT_ID);
@@ -453,7 +539,7 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
         } else {
           whereSql.push(
             keysetBoundarySql(
-              colSql(sortField),
+              referenceSortExpr !== undefined ? referenceSortExpr(params) : colSql(sortField),
               colSql("id"),
               { id: cursor.id, sortValue: cursor.sortValue },
               sortDescending,
@@ -501,17 +587,40 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
       if (payload.filter !== undefined) applyFilter(payload.filter);
       if (payload.filters !== undefined) for (const f of payload.filters) applyFilter(f);
 
+      // The COUNT below reuses the WHERE text only, so it must bind exactly the
+      // params that text references — Postgres rejects a statement supplied
+      // with more parameters than it uses, and ORDER BY may add its own.
+      const whereParams = params.slice();
+
+      const sortSql =
+        sortField === undefined
+          ? undefined
+          : referenceSortExpr !== undefined
+            ? referenceSortExpr(params)
+            : colSql(sortField);
       const orderByClause =
-        sortField !== undefined
-          ? ` ORDER BY ${colSql(sortField)} ${sortDescending ? "DESC" : "ASC"}, ${colSql("id")} ASC`
+        sortSql !== undefined
+          ? ` ORDER BY ${sortSql} ${sortDescending ? "DESC" : "ASC"}, ${colSql("id")} ASC`
           : ` ORDER BY ${colSql("id")} ASC`;
       const useOffset = !payload.cursor && offset > 0;
       const offsetClause = useOffset ? ` OFFSET ${offset}` : "";
 
       const whereClauseSqlText = whereSql.length > 0 ? ` WHERE ${whereSql.join(" AND ")}` : "";
-      const listSql = `SELECT * FROM "${tableName}"${whereClauseSqlText}${orderByClause} LIMIT ${limit}${offsetClause}`;
+      // Project the resolved label too, so the keyset cursor below carries the
+      // value that was ordered by rather than the FK column's UUID.
+      const selectList =
+        referenceSortExpr !== undefined && sortSql !== undefined
+          ? `*, ${sortSql} AS "${SORT_LABEL_ALIAS}"`
+          : "*";
+      const listSql = `SELECT ${selectList} FROM "${tableName}"${whereClauseSqlText}${orderByClause} LIMIT ${limit}${offsetClause}`;
 
       const rawRows = await executeRawQueryRead<Record<string, unknown>>(db.raw, listSql, params);
+      const lastSortLabel = rawRows[rawRows.length - 1]?.[SORT_LABEL_ALIAS];
+      if (referenceSortExpr !== undefined) {
+        // The alias is a sort artifact, not a column of this entity — strip it
+        // before coercion so it never reaches the caller or the entity cache.
+        for (const row of rawRows) delete row[SORT_LABEL_ALIAS];
+      }
       // Per-row read-side rehydrate + snake→camel coercion for driver-agnostic field names.
       // Coerce BEFORE rehydrate/decrypt: the raw SELECT * rows carry snake_case
       // column names, while compound-type lookups (rehydrateMoney et al.) and the
@@ -542,7 +651,11 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
       if (rows.length === limit && lastRow && lastRaw) {
         const cursorId = lastRow["id"] as string; // @cast-boundary engine-payload
         const sortText =
-          sortField === undefined ? undefined : toCursorSortText(lastRaw[physicalCol(sortField)]);
+          sortField === undefined
+            ? undefined
+            : toCursorSortText(
+                referenceSortExpr !== undefined ? lastSortLabel : lastRaw[physicalCol(sortField)],
+              );
         nextCursor =
           sortText === undefined ? encodeCursor(cursorId) : encodeKeysetCursor(sortText, cursorId);
       }
@@ -559,7 +672,11 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
           total = filterIds.length;
         } else {
           const countSql = `SELECT COUNT(*)::int AS count FROM "${tableName}"${whereClauseSqlText}`;
-          const countRows = await executeRawQueryRead<{ count: number }>(db.raw, countSql, params);
+          const countRows = await executeRawQueryRead<{ count: number }>(
+            db.raw,
+            countSql,
+            whereParams,
+          );
           total = countRows[0]?.count ?? 0;
         }
       }

package/src/db/table-builder.ts

@@ -572,6 +572,16 @@ export function buildEntityTable<E extends EntityDefinition>(
         // Pass through to the IndexBuilderWithCols.where()-API.
         if (def.where !== undefined) {
           chain = chain.where(def.where as SqlExpression);
+        } else if (def.unique === true && entity.softDelete === true) {
+          // Soft-deleted rows keep their value, so a full unique index would
+          // permanently block reuse; kept in lock-step with entity-table-meta.ts (framework#2593).
+          const softDeleteWhere: SqlExpression = {
+            kind: "sql-expr",
+            text: `"is_deleted" = false`,
+            params: [],
+            [SQL_EXPR_BRAND]: true,
+          };
+          chain = chain.where(softDeleteWhere);
         }
         indexes[indexName] = chain;
         // Partielles bidx-Pendant für unique-Indices über lookupable-Spalten

package/src/engine/__tests__/engine.test.ts

@@ -150,7 +150,9 @@ describe("defineFeature", () => {
   test("r.defineEvent returns typed EventDef and registers on feature", () => {
     let eventRef: { name: string } | undefined;
     const feature = defineFeature("orders", (r) => {
-      eventRef = r.defineEvent("order:created", z.object({ orderId: z.number() }));
+      eventRef = r.defineEvent("order:created", z.object({ orderId: z.number() }), {
+        piiFields: "none",
+      });
     });
 
     // E.3: defineEvent returns the fully-qualified name so callers can
@@ -185,7 +187,7 @@ describe("defineFeature", () => {
 
   test("registry prefixes event names with feature name", () => {
     const feature = defineFeature("orders", (r) => {
-      r.defineEvent("order:created", z.object({ orderId: z.number() }));
+      r.defineEvent("order:created", z.object({ orderId: z.number() }), { piiFields: "none" });
     });
     const registry = createRegistry([feature]);
     expect(registry.getEvent("orders:event:order:created")).toBeDefined();
@@ -698,6 +700,134 @@ describe("createRegistry", () => {
 
     expect(() => createRegistry([feature])).toThrow(/multiple/);
   });
+
+  test("returns sortable reference fields for entity, without leaking them into getSortableFields (fw#2741)", () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "customer",
+        createEntity({ table: "Customers", fields: { name: createTextField() } }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            note: createTextField({ sortable: true }),
+            customerId: {
+              type: "reference",
+              entity: "customer",
+              labelField: "name",
+              sortable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    const registry = createRegistry([feature]);
+    // getSortableFields lists plain columns the read path can ORDER BY
+    // directly — a reference sorts through its target's label instead.
+    expect(registry.getSortableFields("order")).toEqual(["note"]);
+    expect(registry.getSortableReferences("order")).toEqual([
+      { fieldName: "customerId", targetEntityName: "customer", labelField: "name" },
+    ]);
+    expect(registry.getSortableReferences("nonexistent")).toEqual([]);
+  });
+
+  test("resolves a cross-feature sortable reference to its bare entity name (fw#2741)", () => {
+    const users = defineFeature("users", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: { email: createTextField() } }));
+    });
+    const crm = defineFeature("crm", (r) => {
+      r.entity(
+        "ticket",
+        createEntity({
+          table: "Tickets",
+          fields: {
+            ownerId: {
+              type: "reference",
+              entity: "users:user",
+              labelField: "email",
+              sortable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    const registry = createRegistry([users, crm]);
+    expect(registry.getSortableReferences("ticket")).toEqual([
+      { fieldName: "ownerId", targetEntityName: "user", labelField: "email" },
+    ]);
+  });
+
+  test("throws at boot when a sortable reference field has no explicit labelField (fw#2741)", () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "customer",
+        createEntity({ table: "Customers", fields: { name: createTextField() } }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            customerId: { type: "reference", entity: "customer", sortable: true },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).toThrow(/labelField/);
+  });
+
+  test("throws at boot when a sortable reference field uses labelField: 'id' (fw#2741)", () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity(
+        "customer",
+        createEntity({ table: "Customers", fields: { name: createTextField() } }),
+      );
+      r.entity(
+        "order",
+        createEntity({
+          table: "Orders",
+          fields: {
+            customerId: {
+              type: "reference",
+              entity: "customer",
+              labelField: "id",
+              sortable: true,
+            },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).toThrow(/labelField/);
+  });
+
+  test("throws at boot when sortable is combined with multiple on a reference field (fw#2741)", () => {
+    const feature = defineFeature("crm", (r) => {
+      r.entity("tag", createEntity({ table: "Tags", fields: { name: createTextField() } }));
+      r.entity(
+        "post",
+        createEntity({
+          table: "Posts",
+          fields: {
+            tagIds: {
+              type: "reference",
+              entity: "tag",
+              labelField: "name",
+              sortable: true,
+              multiple: true,
+            },
+          },
+        }),
+      );
+    });
+
+    expect(() => createRegistry([feature])).toThrow(/multiple/);
+  });
 });
 
 // --- Access ---

package/src/engine/__tests__/event-migration-declarative.test.ts

@@ -9,6 +9,7 @@ const upcastCtx = {} as EventUpcastCtx;
 function compile(spec: DeclarativeEventMigration) {
   const feature = defineFeature("billing", (r) => {
     r.defineEvent("invoicePaid", z.unknown(), {
+      piiFields: "none",
       version: 2,
       migrations: [{ fromVersion: 1, toVersion: 2, transform: spec }],
     });
@@ -56,6 +57,7 @@ describe("declarative eventMigration", () => {
     const fn = (payload: unknown) => payload;
     const feature = defineFeature("billing", (r) => {
       r.defineEvent("invoicePaid", z.unknown(), {
+        piiFields: "none",
         version: 2,
         migrations: [{ fromVersion: 1, toVersion: 2, transform: fn }],
       });

package/src/engine/__tests__/extend-entity-projection.test.ts

@@ -21,7 +21,9 @@ describe("r.extendEntityProjection — registration", () => {
   test("merges apply keys + extraSources into the implicit projection", () => {
     const feature = defineFeature("test", (r) => {
       r.entity("unit", exampleEntity());
-      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }), {
+        piiFields: "none",
+      });
       r.extendEntityProjection("unit", {
         sources: ["field-definition"],
         apply: { [setEvent.name]: noopApply },
@@ -39,7 +41,9 @@ describe("r.extendEntityProjection — registration", () => {
   test("extension source equal to the entity name is not duplicated into extraSources", () => {
     const feature = defineFeature("test", (r) => {
       r.entity("unit", exampleEntity());
-      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }), {
+        piiFields: "none",
+      });
       r.extendEntityProjection("unit", {
         sources: ["unit"],
         apply: { [setEvent.name]: noopApply },
@@ -66,7 +70,9 @@ describe("r.extendEntityProjection — registration", () => {
 
   test("registration order is free: extension before r.entity in the same feature", () => {
     const feature = defineFeature("test", (r) => {
-      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }), {
+        piiFields: "none",
+      });
       r.extendEntityProjection("unit", { apply: { [setEvent.name]: noopApply } });
       r.entity("unit", exampleEntity());
     });
@@ -89,7 +95,9 @@ describe("r.extendEntityProjection — registry-build validation", () => {
   test("unknown entity fails at registry build", () => {
     const feature = defineFeature("test", (r) => {
       r.entity("unit", exampleEntity());
-      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }), {
+        piiFields: "none",
+      });
       r.extendEntityProjection("typo-entity", { apply: { [setEvent.name]: noopApply } });
     });
     expect(() => createRegistry([feature])).toThrow(/no r\.entity/);
@@ -106,7 +114,9 @@ describe("r.extendEntityProjection — registry-build validation", () => {
   test("apply-key collision between two extensions fails at registry build", () => {
     const feature = defineFeature("test", (r) => {
       r.entity("unit", exampleEntity());
-      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }));
+      const setEvent = r.defineEvent("custom-field-set", z.object({ fieldKey: z.string() }), {
+        piiFields: "none",
+      });
       r.extendEntityProjection("unit", { apply: { [setEvent.name]: noopApply } });
       r.extendEntityProjection("unit", { apply: { [setEvent.name]: noopApply } });
     });

package/src/engine/__tests__/pipeline-handler.integration.test.ts

@@ -454,7 +454,7 @@ const bulkLogHandler = defineWriteHandler({
 const demoPipelineFeature = defineFeature("demoPipeline", (r) => {
   r.requires.projection("pipeline_demo_log");
   r.entity("widget", widgetEntity);
-  r.defineEvent("annotated", z.object({ note: z.string() }));
+  r.defineEvent("annotated", z.object({ note: z.string() }), { piiFields: "none" });
   r.writeHandler(echoHandler);
   r.writeHandler(explodeHandler);
   r.writeHandler(compoundHandler);

package/src/engine/entity-handlers.ts

@@ -384,6 +384,10 @@ export function defineEntityQueryHandler(
             fields: ctx.registry.getSearchableReferences(entityName),
             resolveEntity: (name) => ctx.registry.getEntity(name),
           },
+          referenceSort: {
+            fields: ctx.registry.getSortableReferences(entityName),
+            resolveEntity: (name) => ctx.registry.getEntity(name),
+          },
         });
         const enrichedRows = hasRefFields
           ? await enrichWithReferences(

package/src/engine/feature-ast/__tests__/canonical-form.test.ts

@@ -56,6 +56,7 @@ defineFeature("todoList", (r) => {
   r.defineEvent({
     name: "taskCompleted",
     schema: z.object({ id: z.string() }),
+    piiFields: "none",
     version: 2,
     migrations: {
       "1": (old) => ({ ...old, done: true }),

package/src/engine/feature-ast/__tests__/parse-happy-path.test.ts

@@ -42,7 +42,7 @@ defineFeature("todoList", (r) => {
     },
   });
 
-  r.defineEvent("taskCompleted", z.object({ id: z.string() }), { version: 1 });
+  r.defineEvent("taskCompleted", z.object({ id: z.string() }), { piiFields: "none", version: 1 });
 
   r.writeHandler(
     "task:create",

package/src/engine/feature-ast/__tests__/parse.test.ts

@@ -2224,7 +2224,7 @@ describe("extractDefineEvent", () => {
   test("captures eventName + version", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.defineEvent("incidentOpened", z.object({ id: z.string() }), { version: 2 });
+  r.defineEvent("incidentOpened", z.object({ id: z.string() }), { piiFields: "none", version: 2 });
 });
 `);
 
@@ -2241,6 +2241,7 @@ defineFeature("f", (r) => {
   r.defineEvent({
     name: "incidentOpened",
     schema: z.object({ id: z.string() }),
+    piiFields: "none",
     version: 2,
     migrations: { "1": (payload) => payload },
   });
@@ -2285,6 +2286,17 @@ defineFeature("f", (r) => {
     expect(result.errors[0]?.methodName).toBe("defineEvent");
   });
 
+  test("emits ParseError when object form is missing the piiFields property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.defineEvent({ name: "incidentOpened", schema: z.object({ id: z.string() }) });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("defineEvent");
+    expect(result.errors[0]?.reason).toContain("piiFields");
+  });
+
   test("emits ParseError when the event name is not a string literal", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
@@ -2304,6 +2316,17 @@ defineFeature("f", (r) => {
 
     expect(result.errors[0]?.methodName).toBe("defineEvent");
   });
+
+  test("emits ParseError when the positional form is missing the piiFields option", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.defineEvent("incidentOpened", z.object({ id: z.string() }), { version: 2 });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("defineEvent");
+    expect(result.errors[0]?.reason).toContain("piiFields");
+  });
 });
 
 describe("extractDefineEvent — migrations (formerly extractEventMigration)", () => {
@@ -2311,6 +2334,7 @@ describe("extractDefineEvent — migrations (formerly extractEventMigration)", (
     const result = parseInline(`
 defineFeature("f", (r) => {
   r.defineEvent("incidentOpened", z.object({ id: z.string() }), {
+    piiFields: "none",
     version: 2,
     migrations: [
       { fromVersion: 1, toVersion: 2, transform: (payload) => ({ ...payload, severity: "low" }) },
@@ -2333,6 +2357,7 @@ defineFeature("f", (r) => {
   r.defineEvent({
     name: "incidentOpened",
     schema: z.object({ id: z.string() }),
+    piiFields: "none",
     version: 2,
     migrations: {
       "1": (payload) => ({ ...payload, severity: "low" }),
@@ -2353,6 +2378,7 @@ defineFeature("f", (r) => {
     const result = parseInline(`
 defineFeature("f", (r) => {
   r.defineEvent("incidentOpened", z.object({ id: z.string() }), {
+    piiFields: "none",
     migrations: [
       "skip-me",
       { fromVersion: "bad", transform: (payload) => payload },

package/src/engine/feature-ast/__tests__/patch.test.ts

@@ -307,6 +307,7 @@ describe("patch coverage for the remaining pattern-kinds", () => {
     createFeaturePatcher(sf).addDefineEvent({
       name: "itemCreated",
       schemaSource: "z.object({ id: z.string() })",
+      piiFieldsSource: '"none"',
       version: 2,
       migrations: { "1": "(old) => old" },
     });

package/src/engine/feature-ast/__tests__/patcher.test.ts

@@ -178,6 +178,7 @@ describe("FeaturePatcher — typed add helpers for mixed (closure-bearing) patte
     p.addDefineEvent({
       name: "stepCompleted",
       schemaSource: "z.object({ id: z.string() })",
+      piiFieldsSource: '"none"',
       version: 2,
       migrations: { "1": '(old) => ({ id: old.id ?? "" })' },
     });

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -86,6 +86,7 @@ function parse(source: string): {
 //     to match the new context.
 const BODY_LOC_KEYS = new Set([
   "schemaSource",
+  "piiFields",
   "handlerBody",
   "fnBody",
   "transformBody",
@@ -228,7 +229,7 @@ defineFeature("workflow", (r) => {
     console.log("step deleted");
   });
 
-  r.defineEvent("stepCompleted", z.object({ id: z.string() }), { version: 1 });
+  r.defineEvent("stepCompleted", z.object({ id: z.string() }), { piiFields: "none", version: 1 });
 
   r.nav({ id: "steps", label: "Steps", screen: "workflow:screen:step-list" });
 });
@@ -458,8 +459,18 @@ describe("renderPattern — single-pattern shape", () => {
         end: { line: 1, column: 1 },
         raw: "z.object({})",
       },
+      piiFields: {
+        file: "x",
+        start: { line: 1, column: 1 },
+        end: { line: 1, column: 1 },
+        raw: '"none"',
+      },
     });
-    expect(out).toBe("r.defineEvent(DOC_INGESTED_EVENT, z.object({}));");
+    expect(out).toBe(
+      ["r.defineEvent(DOC_INGESTED_EVENT, z.object({}), {", '  piiFields: "none",', "});"].join(
+        "\n",
+      ),
+    );
   });
 });
 
@@ -479,7 +490,7 @@ const DOC_INGESTED_EVENT = "docIngested" as const;
 defineFeature("user-data-rights", (r) => {
   r.extendsRegistrar(EXT_TENANT_DATA, { onRegister: () => {} });
   r.useExtension(EXT_TENANT_DATA, "document", { description: "org-scoped" });
-  r.defineEvent(DOC_INGESTED_EVENT, z.object({ id: z.string() }));
+  r.defineEvent(DOC_INGESTED_EVENT, z.object({ id: z.string() }), { piiFields: "none" });
 });
 `;
 
@@ -625,6 +636,7 @@ import { z } from "zod";
 
 defineFeature("billing", (r) => {
   r.defineEvent("invoicePaid", z.object({ totalCents: z.number() }), {
+    piiFields: "none",
     version: 2,
     migrations: [
       {
@@ -656,6 +668,47 @@ describe("render → parse roundtrip — r.defineEvent({ migrations }) fold", ()
   });
 });
 
+const DEFINE_EVENT_WITH_PII_FIELDS_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+defineFeature("mailer", (r) => {
+  r.defineEvent("attempt", z.object({ recipientId: z.string(), recipientAddress: z.string() }), {
+    piiFields: { recipientAddress: { subjectField: "recipientId" } },
+  });
+});
+`;
+
+describe("render → parse roundtrip — r.defineEvent piiFields stance (fw#2558)", () => {
+  test('piiFields: "none" survives parse → render → parse unchanged', () => {
+    const initial = parse(DEFINE_EVENT_WITH_MIGRATIONS_FEATURE);
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: initial.patterns,
+    });
+    expect(rendered).toContain('piiFields: "none",');
+    const reparsed = parse(rendered);
+    expect(reparsed.patterns.map(stripLocations)).toEqual(initial.patterns.map(stripLocations));
+  });
+
+  test("an object-literal piiFields stance survives parse → render → parse unchanged", () => {
+    const initial = parse(DEFINE_EVENT_WITH_PII_FIELDS_FEATURE);
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: initial.patterns,
+    });
+    expect(rendered).toContain('piiFields: { recipientAddress: { subjectField: "recipientId" } }');
+    const reparsed = parse(rendered);
+    expect(reparsed.patterns.map(stripLocations)).toEqual(initial.patterns.map(stripLocations));
+
+    const eventPattern = reparsed.patterns.find((p) => p.kind === "defineEvent");
+    expect(eventPattern?.kind).toBe("defineEvent");
+    if (eventPattern?.kind === "defineEvent") {
+      expect(eventPattern.piiFields.raw).toContain("recipientAddress");
+    }
+  });
+});
+
 // --- Real-compile check ---------------------------------------------------
 //
 // Everything above proves parse(render(patterns)) is structurally faithful.