@cosmicdrift/kumiko-framework 0.289.0 → 0.291.0

package/src/pipeline/__tests__/blind-index-rebuild-guard.integration.test.ts

@@ -0,0 +1,96 @@
+// projection-rebuild aborts instead of silently NULLing an already-populated
+// blind-index column when this process has no blind-index key configured
+// (fw#3091) — see assertNoBlindIndexLoss in db/queries/shadow-swap.ts.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { resetBlindIndexKeyForTests } from "@cosmicdrift/kumiko-framework/testing";
+import { computeBlindIndex, configureBlindIndexKey, decodeBlindIndexKey } from "../../crypto";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { asRawClient } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
+import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
+import { createEventsTable } from "../../event-store";
+import { createProjectionStateTable, rebuildProjection } from "../../pipeline";
+import { createTestDb, type TestDb, TestUsers, unsafeCreateEntityTable } from "../../stack";
+
+const TEST_KEY_B64 = Buffer.alloc(32, 9).toString("base64");
+const TEST_KEY = decodeBlindIndexKey(TEST_KEY_B64);
+
+const personEntity = createEntity({
+  table: "read_bidx_guard_persons",
+  fields: {
+    email: createTextField({ required: true, personal: "self", find: "exact" }),
+  },
+});
+const personFeature = defineFeature("bidxguardtest", (r) => {
+  r.entity("person", personEntity);
+});
+const personTable = buildEntityTable("person", personEntity);
+const implicitName = "bidxguardtest:projection:person-entity";
+
+const admin = TestUsers.admin;
+let testDb: TestDb;
+let tdb: TenantDb;
+const registry = createRegistry([personFeature]);
+const crud = createEventStoreExecutor(personTable, personEntity, { entityName: "person" });
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, personEntity, "person");
+  await createEventsTable(testDb.db);
+  await createProjectionStateTable(testDb.db);
+  tdb = createTenantDb(testDb.db, admin.tenantId);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(
+    `TRUNCATE kumiko_events, read_bidx_guard_persons, kumiko_projections RESTART IDENTITY CASCADE`,
+  );
+  configureBlindIndexKey(TEST_KEY_B64);
+});
+
+afterEach(() => {
+  resetBlindIndexKeyForTests();
+});
+
+async function rawRow(id: string): Promise<Record<string, unknown>> {
+  const rows = await asRawClient(testDb.db).unsafe<Record<string, unknown>>(
+    `SELECT * FROM read_bidx_guard_persons WHERE id = $1`,
+    [id],
+  );
+  const row = rows[0];
+  if (!row) throw new Error(`no row for ${id}`);
+  return row;
+}
+
+describe("projection-rebuild — blind-index loss guard (fw#3091)", () => {
+  test("populated bidx column + no key in this process → rebuild throws, live table untouched", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+    const before = await rawRow(String(created.data.id));
+    expect(before["email_bidx"]).toBe(computeBlindIndex(TEST_KEY, "marc@example.com"));
+
+    resetBlindIndexKeyForTests();
+    await expect(rebuildProjection(implicitName, { db: testDb.db, registry })).rejects.toThrow(
+      /KUMIKO_BLIND_INDEX_KEY/,
+    );
+
+    const after = await rawRow(String(created.data.id));
+    expect(after).toEqual(before);
+  });
+
+  test("populated bidx column + key configured → rebuild succeeds, bidx recomputed", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+
+    await rebuildProjection(implicitName, { db: testDb.db, registry });
+
+    const after = await rawRow(String(created.data.id));
+    expect(after["email_bidx"]).toBe(computeBlindIndex(TEST_KEY, "marc@example.com"));
+  });
+});

package/src/pipeline/active-membership.ts

@@ -97,18 +97,21 @@ export function resolvePrincipalPlugin(registry: Registry): PrincipalStatusPlugi
   return usage.options;
 }
 
-function resolveLifecyclePlugin(registry: Registry): TenantLifecycleStatusPlugin | undefined {
+export function resolveTenantLifecyclePlugin(
+  registry: Registry,
+  caller: string,
+): TenantLifecycleStatusPlugin | undefined {
   const usages = registry.getExtensionUsages(EXT_TENANT_LIFECYCLE_STATUS);
   if (usages.length > 1) {
     throw new InternalError({
-      message: `dispatcher.resolveActiveMembership: multiple "${EXT_TENANT_LIFECYCLE_STATUS}" providers registered — exactly one (or zero) is expected.`,
+      message: `${caller}: multiple "${EXT_TENANT_LIFECYCLE_STATUS}" providers registered — exactly one (or zero) is expected.`,
     });
   }
   const usage = usages[0];
   if (!usage) return undefined;
   if (!isTenantLifecycleStatusPlugin(usage.options)) {
     throw new InternalError({
-      message: `dispatcher.resolveActiveMembership: "${usage.entityName}" registered under "${EXT_TENANT_LIFECYCLE_STATUS}" without a resolveStatus(tenantId, {db}) — extension options must be a TenantLifecycleStatusPlugin.`,
+      message: `${caller}: "${usage.entityName}" registered under "${EXT_TENANT_LIFECYCLE_STATUS}" without a resolveStatus(tenantId, {db}) — extension options must be a TenantLifecycleStatusPlugin.`,
     });
   }
   return usage.options;
@@ -160,7 +163,10 @@ export async function resolveActiveMembershipFn(
     return { kind: "rejected", reason: "principal_blocked" };
   }
 
-  const lifecyclePlugin = resolveLifecyclePlugin(registry);
+  const lifecyclePlugin = resolveTenantLifecyclePlugin(
+    registry,
+    "dispatcher.resolveActiveMembership",
+  );
   if (lifecyclePlugin) {
     const lifecycle = await lifecyclePlugin.resolveStatus(tenantId, { db });
     if (isTeardownRejected(lifecycle, policy)) {

package/src/pipeline/append-event-core.ts

@@ -1,6 +1,6 @@
 import { requestContext } from "../api/request-context";
 import type { DbRunner } from "../db/connection";
-import { toKebab } from "../engine/qualified-name";
+import { qnScope, toKebab } from "../engine/qualified-name";
 import type { AppendEventArgs, Registry, TenantId } from "../engine/types";
 import { InternalError, validationErrorFromZod } from "../errors";
 import { isStreamArchived } from "../event-store/archive";
@@ -32,15 +32,6 @@ export type AppendDomainEventCoreDeps = {
   readonly callerFeature?: string;
 };
 
-// Extract the owning feature from a qualified event name. Events are
-// registered as "<feature>:event:<short>" (see registry.ts qualify()) so the
-// prefix before the first ":" is the owner. Falls back to undefined if the
-// name isn't qualified — callers then skip the cross-feature check.
-function eventOwnerFeature(qualifiedName: string): string | undefined {
-  const idx = qualifiedName.indexOf(":");
-  return idx > 0 ? qualifiedName.slice(0, idx) : undefined;
-}
-
 // System-event prefix: events under this namespace bypass the registry +
 // ownership checks. Reserved for framework-internal coordination (step-
 // engine deferred dispatch, lifecycle signals). The matching MSP filters
@@ -71,7 +62,7 @@ export async function appendDomainEventCore(
   // into kebab-case for the event/handler names (pubsub-orders:event:…) — so
   // we compare the kebab form on both sides.
   if (deps.callerFeature && !isSystemEvent) {
-    const owner = eventOwnerFeature(args.type);
+    const owner = qnScope(args.type);
     const callerKebab = toKebab(deps.callerFeature);
     if (owner && owner !== callerKebab) {
       throw new InternalError({

package/src/pipeline/dispatch-shared.ts

@@ -1,4 +1,4 @@
-import { requestContext } from "../api/request-context";
+import { requestContext, runWithOrigin } from "../api/request-context";
 import type { SseBroker } from "../api/sse-broker";
 import type { DbConnection, DbRunner, DbTx } from "../db/connection";
 import { runInSavepoint, selectMany } from "../db/query";
@@ -907,7 +907,12 @@ export async function runHandlerInstrumented<T>(
       },
       async (span) => {
         try {
-          const result = await inner();
+          // #3043 — everything the handler writes, including entity-executor
+          // writes below it, is attributed to this handler.
+          const result = await runWithOrigin(
+            { handler: type, feature: registry.getHandlerFeature(type) },
+            inner,
+          );
           if (operation === "write" && isFailedWriteResult(result)) {
             success = false;
             errorClass = result.error?.code ?? "UnknownError";
@@ -963,11 +968,18 @@ export async function* runStreamInstrumented<T>(
     attributes: dispatcherSpanAttributes(type, "stream", user, registry.getHandlerFeature(type)),
   });
   const it = inner();
+  // Each pull re-enters both scopes: AsyncLocalStorage does not survive a
+  // generator suspension, so wrapping inner() once would leave every event a
+  // stream writes unattributed.
+  const inScope = <R>(fn: () => R): R =>
+    runWithOrigin({ handler: type, feature: registry.getHandlerFeature(type) }, () =>
+      observabilityContext.run({ activeSpan: span }, fn),
+    );
   try {
-    let next = await observabilityContext.run({ activeSpan: span }, () => it.next());
+    let next = await inScope(() => it.next());
     while (!next.done) {
       yield next.value;
-      next = await observabilityContext.run({ activeSpan: span }, () => it.next());
+      next = await inScope(() => it.next());
     }
     completedNormally = true;
     return next.value;
@@ -980,7 +992,7 @@ export async function* runStreamInstrumented<T>(
   } finally {
     // forward close so inner()'s finally still fires — yield* did this for free
     try {
-      await observabilityContext.run({ activeSpan: span }, () => it.return?.(undefined));
+      await inScope(() => it.return?.(undefined));
     } catch (closeError) {
       // Only fold this in when nothing has already failed — a close-time
       // error while an earlier error is in flight would mask the real

package/src/pipeline/event-dispatcher-delivery.ts

@@ -14,6 +14,7 @@ import {
 } from "../db/queries/event-consumer";
 import { selectEventsHeadId } from "../db/queries/event-store";
 import { coerceRow, extractTableInfo, selectMany } from "../db/query";
+import { qnScope } from "../engine/qualified-name";
 import type { AppContext } from "../engine/types";
 import { eventsTable, toStoredEvent as rowToStoredEvent } from "../event-store";
 import {
@@ -240,9 +241,20 @@ export async function deliverEvents(
       const correlationId = stored.metadata.correlationId ?? requestContext.generateId();
       const causationId = String(stored.id);
       const requestId = requestContext.generateId();
-      await requestContext.run({ requestId, correlationId, causationId }, async () => {
-        await consumer.handler(stored, context);
-      });
+      // #3043 — an event this apply writes is attributed to the consumer, not
+      // to whatever wrote the triggering event; causationId already links back.
+      await requestContext.run(
+        {
+          requestId,
+          correlationId,
+          causationId,
+          handler: consumer.name,
+          feature: consumer.featureName ?? qnScope(consumer.name),
+        },
+        async () => {
+          await consumer.handler(stored, context);
+        },
+      );
       cursor = row.id;
       attempts = 0;
       lastError = null;

package/src/pipeline/projection-rebuild.ts

@@ -9,6 +9,7 @@ import {
 import {
   assertLiveColumnsMatchMeta,
   assertLiveTableHasNoRowLevelSecurity,
+  assertNoBlindIndexLoss,
   assertNoUnreachableLiveRows,
   buildShadowTable,
   type ColumnDriftResult,
@@ -358,6 +359,12 @@ export async function rebuildProjection(
       if (skipped.length > 0) {
         await recordRebuildDeadLetters(tx, projectionName, skipped);
       }
+      // Guard the swap: abort if the process has no blind-index key configured
+      // but the live table already has populated bidx columns — the rebuild
+      // would otherwise silently null them out (fw#3091). Applies to every
+      // projection, not just implicit ones: the shadow always gets a fresh
+      // computeBlindIndexValues() pass regardless of projection kind.
+      await assertNoBlindIndexLoss(tx, meta.tableName, meta, projectionName);
       // Guard the swap: abort if the live table holds a row no event can
       // reconstruct (#498 ghost — direct-inserted without a .created event),
       // which the swap would silently drop. Implicit projections only.

package/src/schema-cli.ts

@@ -10,6 +10,12 @@
 
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join, resolve as resolvePath } from "node:path";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  type KmsWiring,
+  resolveKmsWiringAsync,
+} from "./crypto";
 import {
   assertValidMigrationName,
   baselineMigrations,
@@ -316,6 +322,7 @@ export async function runSchemaCli(
         return 1;
       }
       const { db, close } = createDbConnection(dbUrl);
+      let wiring: KmsWiring | undefined;
       try {
         const result = await runMigrationsFromDir(db, migrationsDir);
         // Framework-Infra-Tabellen (event-store + pipeline-state) — die erfasst
@@ -346,6 +353,19 @@ export async function runSchemaCli(
         // retry it — otherwise a failed rebuild is silently never retried,
         // since the migration itself is already tracked applied (#2464).
         if (options.features) {
+          // A rebuild replays applyEntityEvent, which computes bidx columns from
+          // configureBlindIndexKey/configurePiiSubjectKms — both boot-injected by
+          // run{Prod,Dev}App but never by this standalone CLI (the migrate-db
+          // initContainer). Without wiring them here, a rebuild would silently
+          // null out bidx columns and, for ciphertext, throw only once it hits
+          // the row (fw#3091).
+          wiring = await resolveKmsWiringAsync(process.env, {
+            logPrefix: "[kumiko schema apply]",
+          });
+          if ("kms" in wiring) {
+            configurePiiSubjectKms(wiring.kms);
+            configureBlindIndexKey(wiring.blindIndexKey);
+          }
           const thisRunTables = await queueRebuildsFromMarkers(db, {
             migrationsDir,
             appliedIds: result.applied,
@@ -376,6 +396,7 @@ export async function runSchemaCli(
         out.err("");
         return 1;
       } finally {
+        await wiring?.close();
         await close();
       }
     }

package/src/scripts/codemod/pii-personal-migration.ts

@@ -23,9 +23,11 @@
 //
 // Usage: bun scripts/codemod/pii-personal-migration.ts <targetDir> [--dry-run]
 
+import { readFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { Glob } from "bun";
 import {
+  type CallExpression,
   Node,
   type ObjectLiteralExpression,
   Project,
@@ -33,6 +35,11 @@ import {
   type SourceFile,
   SyntaxKind,
 } from "ts-morph";
+import {
+  PII_DIRECT_NAME_HINTS,
+  PII_USER_OWNED_NAME_HINTS,
+  PII_USER_REFERENCE_NAME_HINTS,
+} from "../../engine/boot-validator/entity-handler";
 
 const SUBJECT_FLAG_NAMES = [
   "pii",
@@ -431,11 +438,242 @@ function findTargetFiles(rootDir: string): string[] {
   return files.sort();
 }
 
+export type StanceClass = "direct" | "user-owned" | "user-reference" | "near-miss" | "unclassified";
+
+export type StanceSite = {
+  readonly line: number;
+  readonly field: string;
+  readonly entity: string | null;
+  readonly callee: string;
+  readonly stance: StanceClass;
+  readonly hint: string | undefined;
+};
+
+const ALL_PII_NAME_HINTS: readonly string[] = [
+  ...PII_DIRECT_NAME_HINTS,
+  ...PII_USER_OWNED_NAME_HINTS,
+  ...PII_USER_REFERENCE_NAME_HINTS,
+];
+
+const REPORT_STANCE_CALLEES = new Set(["createTextField", "createLongTextField"]);
+
+// Mirrors guard-text-field-stance.ts's hasPersonalStance exactly.
+function reportStanceHasPersonalStance(obj: ObjectLiteralExpression): boolean {
+  const prop = obj.getProperty("personal");
+  if (!prop || !Node.isPropertyAssignment(prop)) return false;
+  const init = prop.getInitializer();
+  return (
+    init !== undefined &&
+    init.getKind() !== SyntaxKind.UndefinedKeyword &&
+    !(Node.isIdentifier(init) && init.getText() === "undefined") &&
+    init.getKind() !== SyntaxKind.NullKeyword
+  );
+}
+
+function reportStanceEnclosingFieldName(call: CallExpression): string | undefined {
+  let node = call.getParent();
+  while (node) {
+    if (Node.isPropertyAssignment(node)) return node.getName();
+    node = node.getParent();
+  }
+  return undefined;
+}
+
+function reportStanceResolveEntity(call: CallExpression): string | null {
+  let node: Node | undefined = call.getParent();
+  let entityCall: CallExpression | undefined;
+  while (node) {
+    if (Node.isCallExpression(node)) {
+      const expr = node.getExpression();
+      if (Node.isIdentifier(expr) && expr.getText() === "createEntity") {
+        entityCall = node;
+        break;
+      }
+    }
+    node = node.getParent();
+  }
+  if (!entityCall) return null;
+
+  const firstArg = entityCall.getArguments()[0];
+  if (firstArg && Node.isObjectLiteralExpression(firstArg)) {
+    const tableProp = firstArg.getProperty("table");
+    if (tableProp && Node.isPropertyAssignment(tableProp)) {
+      const init = tableProp.getInitializer();
+      if (init && Node.isStringLiteral(init)) return init.getLiteralText();
+    }
+  }
+  const varDecl = entityCall.getParentIfKind(SyntaxKind.VariableDeclaration);
+  return varDecl ? varDecl.getName() : null;
+}
+
+// A hint only counts at a segment boundary (index 0, an uppercase letter in
+// the original, or preceded by `_`) — otherwise a coincidental substring
+// like "text" inside "contextId" would false-positive.
+function hintOccursAtBoundary(fieldLower: string, fieldOriginal: string, hint: string): boolean {
+  let searchFrom = 0;
+  for (;;) {
+    const index = fieldLower.indexOf(hint, searchFrom);
+    if (index === -1) return false;
+    const atBoundary =
+      index === 0 || /[A-Z]/.test(fieldOriginal[index] ?? "") || fieldOriginal[index - 1] === "_";
+    if (atBoundary) return true;
+    searchFrom = index + 1;
+  }
+}
+
+function findLongestBoundaryHint(fieldLower: string, fieldOriginal: string): string | undefined {
+  let best: string | undefined;
+  for (const hint of ALL_PII_NAME_HINTS) {
+    if (best && hint.length <= best.length) continue;
+    if (hintOccursAtBoundary(fieldLower, fieldOriginal, hint)) best = hint;
+  }
+  return best;
+}
+
+function segmentAlignedSuffixes(fieldOriginal: string): string[] {
+  const fieldLower = fieldOriginal.toLowerCase();
+  const suffixes: string[] = [];
+  for (let index = 0; index < fieldOriginal.length; index++) {
+    const atBoundary =
+      index === 0 || /[A-Z]/.test(fieldOriginal[index] ?? "") || fieldOriginal[index - 1] === "_";
+    if (atBoundary) suffixes.push(fieldLower.slice(index));
+  }
+  return suffixes;
+}
+
+// The hint sets only carry exact full names, so a suffix variant of one
+// (e.g. "...UserId" of "assigneeUserId") otherwise slips through undetected.
+function findShortestHintContainingSuffix(fieldOriginal: string): string | undefined {
+  let best: string | undefined;
+  for (const suffix of segmentAlignedSuffixes(fieldOriginal)) {
+    if (suffix.length < 5) continue;
+    for (const hint of ALL_PII_NAME_HINTS) {
+      if (!hint.includes(suffix)) continue;
+      if (!best || hint.length < best.length) best = hint;
+    }
+  }
+  return best;
+}
+
+function classifyFieldStance(field: string): { stance: StanceClass; hint: string | undefined } {
+  const fieldLower = field.toLowerCase();
+  if (PII_DIRECT_NAME_HINTS.has(fieldLower)) return { stance: "direct", hint: fieldLower };
+  if (PII_USER_OWNED_NAME_HINTS.has(fieldLower)) return { stance: "user-owned", hint: fieldLower };
+  if (PII_USER_REFERENCE_NAME_HINTS.has(fieldLower))
+    return { stance: "user-reference", hint: fieldLower };
+  const containmentHint = findLongestBoundaryHint(fieldLower, field);
+  if (containmentHint) return { stance: "near-miss", hint: containmentHint };
+  const suffixHint = findShortestHintContainingSuffix(field);
+  if (suffixHint) return { stance: "near-miss", hint: suffixHint };
+  return { stance: "unclassified", hint: undefined };
+}
+
+export function reportStanceForSource(source: string, filePath: string): StanceSite[] {
+  const project = new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
+  const sourceFile = project.createSourceFile(filePath, source);
+
+  const sites: StanceSite[] = [];
+  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const exprNode = call.getExpression();
+    if (!Node.isIdentifier(exprNode)) continue;
+    const callee = exprNode.getText();
+    if (!REPORT_STANCE_CALLEES.has(callee)) continue;
+
+    const args = call.getArguments();
+    if (args.length > 0) {
+      const options = args[0];
+      if (!options || !Node.isObjectLiteralExpression(options)) continue;
+      if (options.getProperties().some((p) => p.isKind(SyntaxKind.SpreadAssignment))) continue;
+      if (reportStanceHasPersonalStance(options)) continue;
+    }
+
+    const enclosingField = reportStanceEnclosingFieldName(call);
+    // A call with no enclosing field (e.g. a bare createTextField() at top
+    // level) has no real name to classify — `createTextField(...)` would
+    // otherwise false-positive as a near-miss on its own "Text".
+    const { stance, hint } = enclosingField
+      ? classifyFieldStance(enclosingField)
+      : { stance: "unclassified" as const, hint: undefined };
+
+    sites.push({
+      line: call.getStartLineNumber(),
+      field: enclosingField ?? `${callee}(...)`,
+      entity: reportStanceResolveEntity(call),
+      callee,
+      stance,
+      hint,
+    });
+  }
+  return sites;
+}
+
+function findReportStanceFiles(rootDir: string): string[] {
+  const glob = new Glob("**/*.{ts,tsx}");
+  const EXCLUDE = ["/node_modules/", "/dist/", "/build/"];
+  const files: string[] = [];
+  for (const file of glob.scanSync({ cwd: rootDir, dot: false })) {
+    if (file.endsWith(".d.ts")) continue;
+    const abs = resolve(rootDir, file);
+    if (EXCLUDE.some((p) => abs.includes(p))) continue;
+    files.push(abs);
+  }
+  return files.sort();
+}
+
+function reportStance(rootDir: string): void {
+  console.log(
+    `Scanning every .ts/.tsx under ${rootDir} except node_modules/dist/build/*.d.ts — guard-text-field-stance scans packages/*/src/** only, so counts can differ outside that scope.`,
+  );
+
+  const totals: Record<StanceClass, number> = {
+    direct: 0,
+    "user-owned": 0,
+    "user-reference": 0,
+    "near-miss": 0,
+    unclassified: 0,
+  };
+  let total = 0;
+
+  for (const file of findReportStanceFiles(rootDir)) {
+    const sites = reportStanceForSource(readFileSync(file, "utf8"), file);
+    if (sites.length === 0) continue;
+
+    console.log(`\n${relative(rootDir, file)}`);
+    for (const site of sites) {
+      totals[site.stance]++;
+      total++;
+      const entity = site.entity ?? "<unresolved>";
+      const hintSuffix = site.hint ? ` (hint: ${site.hint})` : "";
+      console.log(
+        `  ${site.line}  ${site.field}  entity=${entity}  ${site.callee}  ${site.stance}${hintSuffix}`,
+      );
+    }
+  }
+
+  console.log("\nBy stance:");
+  for (const [stance, count] of Object.entries(totals)) {
+    if (count > 0) console.log(`  ${stance}: ${count}`);
+  }
+  console.log(`Total: ${total}`);
+
+  if (totals["near-miss"] > 0) {
+    console.log(
+      "\nHint sets in entity-handler.ts are exact name matches — near-miss field names slip past the boot heuristic.",
+    );
+  }
+}
+
 async function main(): Promise<void> {
   const positional = process.argv.slice(2).filter((a) => !a.startsWith("--"));
-  const dryRun = process.argv.includes("--dry-run");
   const rootDir = resolve(positional[0] ?? process.cwd());
 
+  if (process.argv.includes("--report-stance")) {
+    reportStance(rootDir);
+    // skip: report mode never rewrites, so the transform path below must not run
+    return;
+  }
+
+  const dryRun = process.argv.includes("--dry-run");
   const files = findTargetFiles(rootDir);
   const project = new Project({
     skipAddingFilesFromTsConfig: true,
@@ -477,4 +715,6 @@ async function main(): Promise<void> {
   }
 }
 
-await main();
+if (import.meta.main) {
+  await main();
+}

package/src/stack/__tests__/ownership-boot-guard.integration.test.ts

@@ -37,7 +37,7 @@ function memoEntity(access: Parameters<typeof createEntity>[0]["access"]) {
   return createEntity({
     table: "fwbootguard_memos",
     fields: {
-      ownerId: createTextField({ required: true }),
+      ownerId: createTextField({ personal: false, reason: "test_fixture", required: true }),
       title: createTextField({ personal: false, reason: "test_fixture", required: true }),
     },
     ...(access ? { access } : {}),

package/src/testing/__tests__/e2e-generator.test.ts

@@ -97,6 +97,56 @@ describe("generateE2ESpec", () => {
     ]);
   });
 
+  test("groups-only sections liefern Required-Felder, Fill-Ops und Text-Assertion", () => {
+    const feature = defineFeature("tasks", (r) => {
+      r.systemScope();
+      r.entity("task", taskEntity);
+      r.writeHandler(
+        defineEntityCreateHandler("task", taskEntity, {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        }),
+      );
+      r.screen({
+        id: "task-list",
+        type: "entityList",
+        entity: "task",
+        columns: ["title", "status", "done"],
+      });
+      r.screen({
+        id: "task-edit",
+        type: "entityEdit",
+        entity: "task",
+        layout: {
+          sections: [
+            {
+              title: "tasks:section.basics",
+              fields: [],
+              groups: [
+                { title: "tasks:group.core", fields: ["title", "status"] },
+                { title: "tasks:group.state", fields: ["done"] },
+              ],
+            },
+          ],
+        },
+      });
+    });
+    const specs = generateE2ESpec(createRegistry([feature]));
+    const editSpecs = specs.filter((s) => s.screenQn === "tasks:screen:task-edit");
+
+    const validates = editSpecs.find((s) => s.kind === "edit-validates-required");
+    if (validates?.kind !== "edit-validates-required") throw new Error("unreachable");
+    expect(validates.requiredFields).toEqual(["title"]);
+
+    const persists = editSpecs.find((s) => s.kind === "edit-save-persists");
+    if (persists?.kind !== "edit-save-persists") throw new Error("unreachable");
+    expect(persists.fills).toEqual([
+      { kind: "fill", field: "title", value: "e2e title" },
+      { kind: "select", field: "status", value: "todo" },
+      { kind: "check", field: "done", value: true },
+    ]);
+    expect(persists.identifyingField).toBe("title");
+  });
+
   test("date emittiert fill, timestamp wird übersprungen (zwei Inputs seit #369)", () => {
     const entity = createEntity({
       table: "events",