@cosmicdrift/kumiko-framework 0.288.0 → 0.289.0

package/src/i18n/required-surface-keys.ts

@@ -1,8 +1,10 @@
 import { isExplicitDotFormKey } from "../engine/i18n-key";
+import type { FieldsOrGroupsSection } from "../engine/screen-helpers";
 import {
   isExtensionEditSection,
   isWriteFormEditSection,
   normalizeListColumn,
+  sectionFieldSpecs,
 } from "../engine/screen-helpers";
 import type {
   ActionFormScreenDefinition,
@@ -82,6 +84,16 @@ function editFieldName(f: string | { readonly field: string }): string {
   return typeof f === "string" ? f : f.field;
 }
 
+// Group titles are translated exactly like the section title (computeEditViewModel).
+function pushSectionTitles(
+  out: Set<string>,
+  section: { readonly title?: string } & FieldsOrGroupsSection,
+  treatAsKey = false,
+): void {
+  pushKey(out, section.title, treatAsKey);
+  for (const group of section.groups ?? []) pushKey(out, group.title, treatAsKey);
+}
+
 function pushRowActionKeys(out: Set<string>, action: RowAction): void {
   pushKey(out, action.label);
   if (action.kind === "writeHandler" || action.kind === undefined) {
@@ -182,8 +194,8 @@ export function requiredKeysFromScreen(
           continue;
         }
         if (section.kind === "relatedList") continue; // rejected at boot, unreachable here
-        pushKey(out, section.title);
-        for (const f of section.fields) {
+        pushSectionTitles(out, section);
+        for (const f of sectionFieldSpecs(section)) {
           const fieldName = editFieldName(f);
           const override = edit.fieldLabels?.[fieldName];
           if (override !== undefined) pushKey(out, override);
@@ -206,8 +218,8 @@ export function requiredKeysFromScreen(
           continue;
         }
         if (section.kind === "relatedList") continue; // rejected at boot, unreachable here
-        pushKey(out, section.title);
-        for (const f of section.fields) {
+        pushSectionTitles(out, section);
+        for (const f of sectionFieldSpecs(section)) {
           const fieldName = editFieldName(f);
           const override = form.fieldLabels?.[fieldName];
           if (override !== undefined) pushKey(out, override);
@@ -230,8 +242,8 @@ export function requiredKeysFromScreen(
           continue;
         }
         if (section.kind === "relatedList") continue; // rejected at boot, unreachable here
-        pushKey(out, section.title);
-        for (const f of section.fields) {
+        pushSectionTitles(out, section);
+        for (const f of sectionFieldSpecs(section)) {
           const fieldName = editFieldName(f);
           out.add(fieldLabelKey(featureName, ACTION_FORM_ENTITY, fieldName));
         }
@@ -254,8 +266,8 @@ export function requiredKeysFromScreen(
             continue;
           }
           if (section.kind === "relatedList") continue; // rejected at boot, unreachable here
-          pushKey(out, section.title);
-          for (const f of section.fields) {
+          pushSectionTitles(out, section);
+          for (const f of sectionFieldSpecs(section)) {
             const fieldName = editFieldName(f);
             out.add(fieldLabelKey(featureName, ACTION_FORM_ENTITY, fieldName));
           }
@@ -277,8 +289,8 @@ export function requiredKeysFromScreen(
           continue;
         }
         if (section.kind === "relatedList") continue; // rejected at boot, unreachable here
-        pushKey(out, section.title, treatDotFormAsKey);
-        for (const f of section.fields) {
+        pushSectionTitles(out, section, treatDotFormAsKey);
+        for (const f of sectionFieldSpecs(section)) {
           const fieldName = editFieldName(f);
           const override = config.fieldLabels?.[fieldName];
           if (override !== undefined) pushKey(out, override, treatDotFormAsKey);
@@ -322,8 +334,8 @@ export function requiredKeysFromScreen(
           }
           continue;
         }
-        pushKey(out, section.title);
-        for (const f of section.fields) {
+        pushSectionTitles(out, section);
+        for (const f of sectionFieldSpecs(section)) {
           const fieldName = editFieldName(f);
           const override = detail.fieldLabels?.[fieldName];
           if (override !== undefined) pushKey(out, override);

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/dispatch-shared.ts

@@ -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;
 }

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