@cosmicdrift/kumiko-framework 0.288.0 → 0.290.0

package/src/pipeline/__tests__/member-resolution-read-only.test.ts

@@ -0,0 +1,79 @@
+// createUncheckedSystemDb's grantedUnsafeRawRunner (db/tenant-db.ts) hands out a
+// raw runner without a grant check. Under a resolved member principal that door
+// is closed only because applyMemberResolutionReadOnly drops systemDb and
+// dbOutsideTransaction — this pins that, plus the write surfaces it neutralizes.
+import { describe, expect, test } from "bun:test";
+import type { HandlerContext } from "../../engine/types";
+import { AccessDeniedError, FrameworkReasons } from "../../errors";
+import { applyMemberResolutionReadOnly } from "../dispatch-shared";
+
+const DROPPED_SURFACES = ["systemDb", "dbOutsideTransaction", "runPreSave", "files", "derivatives"];
+
+const DENIED_CALLS = [
+  "write",
+  "writeAs",
+  "queryAs",
+  "appendEvent",
+  "unsafeAppendEvent",
+  "tryAppendEvent",
+  "fetchForWriting",
+  "archiveStream",
+  "restoreStream",
+  "snapshotAggregate",
+  "queryAsMember",
+  "resolveActiveMembership",
+  "notify",
+];
+
+function readOnlyContext(): Record<string, unknown> {
+  const wired = Object.fromEntries(
+    [...DROPPED_SURFACES, ...DENIED_CALLS, "scheduleAfterCommit"].map((key) => [
+      key,
+      () => "escalated",
+    ]),
+  );
+  // @cast-boundary test stub — applyMemberResolutionReadOnly only spreads and overwrites.
+  const ctx = { ...wired, jobRunner: { handleEvent: () => "ran" } } as unknown as HandlerContext;
+  return applyMemberResolutionReadOnly(ctx) as unknown as Record<string, unknown>;
+}
+
+function surface(readOnly: Record<string, unknown>, key: string): unknown {
+  return readOnly[key];
+}
+
+describe("applyMemberResolutionReadOnly", () => {
+  test("drops every surface that could reach an unchecked system-scope db", () => {
+    const readOnly = readOnlyContext();
+
+    for (const key of DROPPED_SURFACES) {
+      expect(surface(readOnly, key)).toBeUndefined();
+    }
+  });
+
+  test.each(DENIED_CALLS)("%s rejects with the member-resolution reason", async (call) => {
+    // @cast-boundary test stub — every denied surface is a call returning a promise.
+    const denied = surface(readOnlyContext(), call) as () => Promise<unknown>;
+
+    const error = await denied().then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+
+    expect(error).toBeInstanceOf(AccessDeniedError);
+    // @cast-boundary narrowed by the assertion above.
+    expect((error as AccessDeniedError).details).toMatchObject({
+      reason: FrameworkReasons.memberResolutionReadOnly,
+    });
+  });
+
+  test("scheduleAfterCommit and the jobRunner proxy throw synchronously", () => {
+    const readOnly = readOnlyContext();
+    // @cast-boundary test stub — sync surfaces, not promise-returning.
+    const scheduleAfterCommit = surface(readOnly, "scheduleAfterCommit") as () => void;
+    // @cast-boundary test stub — denyingJobRunnerProxy throws on any property read.
+    const jobRunner = surface(readOnly, "jobRunner") as { handleEvent: unknown };
+
+    expect(() => scheduleAfterCommit()).toThrow(AccessDeniedError);
+    expect(() => jobRunner.handleEvent).toThrow(AccessDeniedError);
+  });
+});

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";
@@ -31,10 +31,9 @@ import type {
 import { isRateLimitDisabled } from "../engine/types";
 import type { TenantId } from "../engine/types/identifiers";
 import {
-  AccessDeniedError,
   FeatureDisabledError,
-  FrameworkReasons,
   InternalError,
+  memberResolutionReadOnlyDenied,
   VersionConflictError,
   type WriteErrorInfo,
 } from "../errors";
@@ -176,7 +175,7 @@ async function appendDomainEvent(
   callerFeature: string | undefined,
 ): Promise<void> {
   // Sink behind every append surface, so a resolved member stays read-only even via fetchForWriting handles.
-  if (user.origin === "member-resolution") throw memberResolutionReadOnlyDenied();
+  if (isMemberResolutionPrincipal(user)) throw memberResolutionReadOnlyDenied();
   const { registry } = ctx;
   const dbSource = resolveDbSource(ctx, tx);
   if (!dbSource) {
@@ -222,12 +221,8 @@ function createSystemScopedDbGuard(
   });
 }
 
-export function memberResolutionReadOnlyDenied(cause?: unknown): AccessDeniedError {
-  return new AccessDeniedError({
-    message: "a resolved member principal (ctx.queryAsMember) cannot write — read-only",
-    details: { reason: FrameworkReasons.memberResolutionReadOnly },
-    ...(cause instanceof Error && { cause }),
-  });
+export function isMemberResolutionPrincipal(user: SessionUser): boolean {
+  return user.origin === "member-resolution";
 }
 
 async function denyMemberResolutionWrite(): Promise<never> {
@@ -246,10 +241,11 @@ function denyingJobRunnerProxy(): JobRunnerRef {
 
 // Every write/side-effect surface throws, so "no writeAsMember" holds even
 // if a handler tries ctx.write directly on a resolved member principal.
-function applyMemberResolutionReadOnly(handlerContext: HandlerContext): HandlerContext {
+export function applyMemberResolutionReadOnly(handlerContext: HandlerContext): HandlerContext {
   return {
     ...handlerContext,
-    // `db` stays open — executeQuery runs the whole handler in a Postgres READ ONLY transaction.
+    // `db` stays open — executeQuery runs the whole handler in a Postgres READ ONLY
+    // transaction, and its `memberReadOnly` grant denies every raw-runner handout.
     dbOutsideTransaction: undefined,
     write: denyMemberResolutionWrite,
     writeAs: denyMemberResolutionWrite,
@@ -319,7 +315,12 @@ export async function buildHandlerContext(
       context.tracer,
       context.meter,
       signal,
-      { globalWrites: writeEscapeHatch, unsafeRaw: handlerEscapeHatch, report: reportEscapeHatch },
+      {
+        globalWrites: writeEscapeHatch,
+        unsafeRaw: handlerEscapeHatch,
+        report: reportEscapeHatch,
+        memberReadOnly: isMemberResolutionPrincipal(user),
+      },
     );
   // Propagate the request's AbortSignal so every TenantDb query throws when
   // the client has disconnected — handlers with many sequential queries skip
@@ -865,7 +866,7 @@ export async function buildHandlerContext(
   } as HandlerContext; // @cast-boundary engine-bridge
 
   // A resolved member principal is read-only by construction.
-  return user.origin === "member-resolution"
+  return isMemberResolutionPrincipal(user)
     ? applyMemberResolutionReadOnly(handlerContext)
     : handlerContext;
 }
@@ -906,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";
@@ -962,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;
@@ -979,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/dispatch-stream.ts

@@ -1,13 +1,18 @@
 import { hasAccess } from "../engine/access";
 import type { SessionUser } from "../engine/types";
-import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors";
+import {
+  AccessDeniedError,
+  memberResolutionReadOnlyDenied,
+  NotFoundError,
+  validationErrorFromZod,
+} from "../errors";
 import { assertNoSecretLeak } from "../secrets";
 import {
   buildHandlerContext,
   type DispatchContext,
   enforceRateLimit,
   ensureFeatureEnabled,
-  memberResolutionReadOnlyDenied,
+  isMemberResolutionPrincipal,
   runStreamInstrumented,
 } from "./dispatch-shared";
 
@@ -38,7 +43,7 @@ async function* executeStreamInner(
 
   // A resolved member principal (ctx.queryAsMember) is read-only — streams
   // are excluded the same way executeWriteInner excludes writes.
-  if (user.origin === "member-resolution") {
+  if (isMemberResolutionPrincipal(user)) {
     throw memberResolutionReadOnlyDenied();
   }
 

package/src/pipeline/dispatch-write.ts

@@ -15,6 +15,7 @@ import {
   FrameworkReasons,
   InternalError,
   isKumikoError,
+  memberResolutionReadOnlyDenied,
   NotFoundError,
   ValidationError,
   validationErrorFromZod,
@@ -28,7 +29,7 @@ import {
   CONFIG_WRITE_SET_TYPE,
   checkFeatureEnabled,
   enforceRateLimit,
-  memberResolutionReadOnlyDenied,
+  isMemberResolutionPrincipal,
   resolveDbSource,
   runHandlerInstrumented,
   TENANT_TIMEZONE_CONFIG_KEY,
@@ -371,7 +372,7 @@ async function executeWriteInner(
 
   // Defense in depth — covers runBatch and a spread-copied user that kept
   // `origin`, beyond buildHandlerContext's own ctx.write replacement.
-  if (user.origin === "member-resolution") {
+  if (isMemberResolutionPrincipal(user)) {
     return writeFailure(memberResolutionReadOnlyDenied());
   }
 

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/event-dispatcher.ts

@@ -127,6 +127,13 @@ export type EventDispatcher = {
   // a full stop/start cycle. Production never needs this — start() runs
   // it once on boot and the rows survive dispatcher lifetime.
   ensureRegistered(): Promise<void>;
+  // Waits out a pass already in flight, without touching the timer or the
+  // LISTEN subscription — unlike stop(), the dispatcher keeps running
+  // afterwards. Test-teardown surface: a beforeEach/afterEach that resets
+  // the events table (TRUNCATE) must not race a pass this same dispatcher
+  // started (timer tick or NOTIFY wake-up) that is still writing into the
+  // tables the reset is about to wipe. No-op when nothing is in flight.
+  drain(): Promise<void>;
   // Read-only view of the consumers this dispatcher is wired with. Exists
   // for lane-filter assertions (Welle 2.6.b split-deploy tests) and for
   // the boot-validator (Welle 2.6.c coverage check: every registered MSP
@@ -253,6 +260,14 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
   // pattern so behaviour under races stays predictable.
   let passInFlight: Promise<DispatcherPassResult> | null = null;
 
+  async function drainPassInFlight(): Promise<void> {
+    if (passInFlight) {
+      await passInFlight.catch(() => {
+        // skip: errors already recorded per-consumer inside the pass
+      });
+    }
+  }
+
   async function runOnce(): Promise<DispatcherPassResult> {
     if (!preRegistered) {
       throw new Error(
@@ -529,11 +544,7 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
       }
 
       // Drain any in-flight pass so shutdown observes consistent state.
-      if (passInFlight) {
-        await passInFlight.catch(() => {
-          // skip: errors already recorded per-consumer inside the pass
-        });
-      }
+      await drainPassInFlight();
       // preRegistered stays true — the rows survive stop(). runOnce()
       // after a stop() still works (tests stop the timer and then drain
       // deterministically).
@@ -544,6 +555,8 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
       preRegistered = true;
     },
 
+    drain: drainPassInFlight,
+
     runOnce,
   };
 }

package/src/pipeline/member-read-only-transaction.ts

@@ -1,12 +1,8 @@
 import type { DbTx } from "../db/connection";
 import { extractPgError } from "../db/pg-error";
 import { asRawClient, runInSavepoint, transaction } from "../db/query";
-import { AccessDeniedError, InternalError } from "../errors";
-import {
-  type DispatchContext,
-  memberResolutionReadOnlyDenied,
-  resolveDbSource,
-} from "./dispatch-shared";
+import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied } from "../errors";
+import { type DispatchContext, resolveDbSource } from "./dispatch-shared";
 
 const PG_READ_ONLY_SQLSTATE = "25006";
 

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/stack/table-helpers.ts

@@ -146,6 +146,12 @@ export async function resetEventStore(
   stack: { db: unknown; eventDispatcher?: EventDispatcher },
   extraTables: readonly (unknown | string)[] = [],
 ): Promise<void> {
+  // A pass the dispatcher's own timer/LISTEN already started (from a
+  // preceding test) may still be writing into the tables truncated below —
+  // drain it first so the TRUNCATE never races a write it didn't cause.
+  if (stack.eventDispatcher) {
+    await stack.eventDispatcher.drain();
+  }
   const frameworkTables = [
     "kumiko_events",
     "kumiko_event_consumers",

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",

package/src/testing/e2e-generator.ts

@@ -36,6 +36,7 @@ import {
   parseQn,
   qn,
   type Registry,
+  sectionFieldSpecs,
   toKebab,
 } from "../engine";
 
@@ -249,7 +250,7 @@ function collectRequiredEditFields(
   const out: string[] = [];
   for (const section of screen.layout.sections) {
     if (!isFieldsEditSection(section)) continue;
-    for (const rawField of section.fields) {
+    for (const rawField of sectionFieldSpecs(section)) {
       const { field } = normalizeEditField(rawField);
       const def = entity.fields[field];
       if (def && "required" in def && def.required === true) {
@@ -287,7 +288,7 @@ function buildEditFillOps(
   const ops: EditFillOp[] = [];
   for (const section of screen.layout.sections) {
     if (!isFieldsEditSection(section)) continue;
-    for (const raw of section.fields) {
+    for (const raw of sectionFieldSpecs(section)) {
       const { field } = normalizeEditField(raw);
       const def = entity.fields[field];
       if (!def) continue;
@@ -335,7 +336,7 @@ function pickIdentifyingForEdit(
 
   for (const section of editScreen.layout.sections) {
     if (!isFieldsEditSection(section)) continue;
-    for (const rawField of section.fields) {
+    for (const rawField of sectionFieldSpecs(section)) {
       const { field } = normalizeEditField(rawField);
       if (entity.fields[field]?.type !== "text") continue;
       if (columns && !columns.has(field)) continue;

package/src/ui-types/index.ts

@@ -25,6 +25,7 @@ export type { DerivedCellRoundingTarget } from "../engine/embedded-derived";
 export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedded-derived";
 export type { ParsedRefTarget } from "../engine/parse-ref-target";
 export { parseRefTarget } from "../engine/parse-ref-target";
+export type { FieldsOrGroupsSection } from "../engine/screen-helpers";
 export {
   evalFieldCondition,
   explicitListScreenId,
@@ -35,6 +36,7 @@ export {
   normalizeEditField,
   normalizeListColumn,
   resolveNavParentScreen,
+  sectionFieldSpecs,
 } from "../engine/screen-helpers";
 // Entity + field types. EntityDefinition is the canonical shape that
 // view-model builders iterate; FieldDefinition is the per-field union