@cosmicdrift/kumiko-framework 0.149.2 → 0.150.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.149.2",
+  "version": "0.150.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -193,7 +193,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.149.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.150.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -90,6 +90,81 @@ describe("r.screen() — registration", () => {
     expect(() => validateBoot(features)).toThrow(/empty or non-string query/i);
   });
 
+  test("stores a projectionDetail screen bound to an explicit query", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "ledger:query:schedule:detail",
+        layout: { sections: [{ title: "app:section.basics", fields: ["description"] }] },
+      });
+    });
+    const screen = feature.screens["rent-detail"];
+    expect(screen?.type).toBe("projectionDetail");
+    if (screen?.type !== "projectionDetail") throw new Error("type-narrow failed");
+    expect(screen.query).toBe("ledger:query:schedule:detail");
+  });
+
+  test("validateBoot rejects a projectionDetail with an empty query", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "",
+          layout: { sections: [{ title: "s", fields: ["name"] }] },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/empty or non-string query/i);
+  });
+
+  test("validateBoot rejects a projectionDetail with empty sections", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: { sections: [] },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/empty sections list/i);
+  });
+
+  test("validateBoot rejects a projectionDetail section with zero fields", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: { sections: [{ title: "s", fields: [] }] },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/zero fields/i);
+  });
+
+  test("validateBoot rejects a projectionDetail with an extension section (no entity to persist against)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              { kind: "extension", title: "s", component: { react: { __component: "c" } } },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/extension section/i);
+  });
+
   test("stores an entityEdit screen with sections + conditional fields", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", productEntity());

package/src/engine/boot-validator/__tests__/config-deps.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { createSystemConfig } from "../../config-helpers";
+import type { FeatureDefinition } from "../../types";
+import { validateConfigKeyAllowPerRequest, validateConfigKeyComputed } from "../config-deps";
+
+function fakeFeature(configKeys: FeatureDefinition["configKeys"]): FeatureDefinition {
+  return { name: "test-feature", configKeys } as unknown as FeatureDefinition;
+}
+
+describe("validateConfigKeyComputed", () => {
+  test("rejects computed + backing:secrets (encrypted-at-rest via backing, not the encrypted flag)", () => {
+    const feature = fakeFeature({
+      apiKey: createSystemConfig("text", { backing: "secrets", computed: async () => "x" }),
+    });
+    expect(() => validateConfigKeyComputed(feature)).toThrow(/mutually exclusive/);
+  });
+
+  test("rejects computed + encrypted:true", () => {
+    const feature = fakeFeature({
+      apiKey: createSystemConfig("text", { encrypted: true, computed: async () => "x" }),
+    });
+    expect(() => validateConfigKeyComputed(feature)).toThrow(/mutually exclusive/);
+  });
+
+  test("allows computed without encryption", () => {
+    const feature = fakeFeature({
+      apiKey: createSystemConfig("text", { computed: async () => "x" }),
+    });
+    expect(() => validateConfigKeyComputed(feature)).not.toThrow();
+  });
+});
+
+describe("validateConfigKeyAllowPerRequest", () => {
+  test("rejects allowPerRequest + backing:secrets on a number key", () => {
+    const feature = fakeFeature({
+      rateLimit: createSystemConfig("number", { backing: "secrets", allowPerRequest: true }),
+    });
+    expect(() => validateConfigKeyAllowPerRequest(feature)).toThrow(
+      /may not be set via query-params/,
+    );
+  });
+});

package/src/engine/boot-validator/config-deps.ts

@@ -1,3 +1,4 @@
+import { isEncryptedAtRest } from "../config-helpers";
 import type { FeatureDefinition } from "../types";
 
 // --- Toggleable-dependency warnings ---
@@ -79,9 +80,9 @@ export function validateConfigKeyComputed(feature: FeatureDefinition): void {
     // returns a plain value, encrypted expects cipher-text in the row. The
     // cascade doesn't know which one to prefer on write. Rejecting at boot
     // is cheaper than surprising behaviour at runtime.
-    if (keyDef.encrypted) {
+    if (isEncryptedAtRest(keyDef)) {
       throw new Error(
-        `[Feature ${feature.name}] Config key "${keyName}" has both encrypted=true and a computed resolver — these are mutually exclusive paradigms`,
+        `[Feature ${feature.name}] Config key "${keyName}" has both encrypted/backing="secrets" and a computed resolver — these are mutually exclusive paradigms`,
       );
     }
   }
@@ -128,9 +129,9 @@ export function validateConfigKeyAllowPerRequest(feature: FeatureDefinition): vo
     // encrypted + per-request would expose a cipher-text interpretation
     // to query-strings. The secret-value shouldn't be transported this
     // way — reject as a paradigm-mismatch.
-    if (keyDef.encrypted) {
+    if (isEncryptedAtRest(keyDef)) {
       throw new Error(
-        `[Feature ${feature.name}] Config key "${keyName}" has allowPerRequest=true but encrypted=true — secret values may not be set via query-params`,
+        `[Feature ${feature.name}] Config key "${keyName}" has allowPerRequest=true but encrypted/backing="secrets" — secret values may not be set via query-params`,
       );
     }
   }

package/src/engine/boot-validator/screens.ts

@@ -172,6 +172,39 @@ export function validateScreens(
       continue;
     }
 
+    if (screen.type === "projectionDetail") {
+      // Query-getrieben wie projectionList, aber Single-Row + Layout statt
+      // Columns. Kein Entity-Check möglich — Felder werden render-seitig
+      // gegen die Query-Response aufgelöst, nicht gegen eine Entity.
+      if (!screen.query || typeof screen.query !== "string") {
+        throw new Error(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has empty or non-string query.`,
+        );
+      }
+      if (screen.layout.sections.length === 0) {
+        throw new Error(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has an empty sections list — ` +
+            `declare at least one section.`,
+        );
+      }
+      for (const section of screen.layout.sections) {
+        if (isExtensionEditSection(section)) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) extension section ` +
+              `"${section.title}" is not supported — projectionDetail has no entity for an extension ` +
+              `section to persist against.`,
+          );
+        }
+        if (section.fields.length === 0) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has a section "${section.title}" ` +
+              `with zero fields — drop the section or add fields to it.`,
+          );
+        }
+      }
+      continue;
+    }
+
     if (screen.type === "dashboard") {
       validateDashboardScreen(feature.name, screenId, screen);
       continue;

package/src/engine/config-helpers.ts

@@ -14,6 +14,17 @@ import type {
   CreateUserSeedOptions,
 } from "./types";
 
+// A key backed by "secrets" is at-rest encrypted by the secrets store itself
+// (MasterKeyProvider), even without an explicit `encrypted: true` — callers
+// that gate on encryption (boot-validator mutual-exclusion checks, config
+// query redaction) must treat the two as equivalent or a secrets-backed key
+// silently skips the encrypted-only guard.
+export function isEncryptedAtRest(
+  def: Pick<ConfigKeyDefinition, "encrypted" | "backing">,
+): boolean {
+  return def.encrypted === true || def.backing === "secrets";
+}
+
 // --- Access Presets ---
 
 export const access = {

package/src/engine/feature-manifest.ts

@@ -7,6 +7,7 @@
 // lesen.
 
 import { compareByCodepoint } from "../utils";
+import { isEncryptedAtRest } from "./config-helpers";
 import { qualifyEntityName } from "./qualified-name";
 import type { Registry, UiHints } from "./types/feature";
 
@@ -106,7 +107,7 @@ export function buildManifestFromRegistry(
         type: def.type,
         scope: def.scope,
         default: def.default ?? null,
-        encrypted: def.encrypted ?? def.backing === "secrets",
+        encrypted: isEncryptedAtRest(def),
         computed: def.computed !== undefined,
         options: def.options ?? null,
         bounds: def.bounds ?? null,

package/src/engine/index.ts

@@ -23,6 +23,7 @@ export {
   createTenantSeed,
   createUserConfig,
   createUserSeed,
+  isEncryptedAtRest,
 } from "./config-helpers";
 export type { SystemHookName } from "./constants";
 export {

package/src/engine/types/handlers.ts

@@ -393,6 +393,13 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
   // (appendEvent) is the contract Designer/AI rely on.
   readonly unsafeAppendEvent: UnsafeAppendEventFn;
 
+  // Savepoint-scoped append. Use when the handler must gracefully continue
+  // after losing a race against a concurrent writer on the same aggregate
+  // stream (e.g. two idempotent ingest calls racing the same dedup key) —
+  // see TryAppendEventFn for why this doesn't poison the transaction the
+  // way a caught unsafeAppendEvent throw would.
+  readonly tryAppendEvent: TryAppendEventFn;
+
   // Marten FetchForWriting equivalent: load the current stream, optionally
   // enforce expectedVersion, and get a handle that appends further events
   // onto that stream without re-specifying aggregateId/aggregateType.
@@ -673,6 +680,20 @@ export type AppendEventFn<TMap extends object = KumikoEventTypeMap> = <K extends
 
 export type UnsafeAppendEventFn = (args: AppendEventArgs) => Promise<void>;
 
+// Savepoint-scoped append — returns a discriminated result instead of
+// throwing on VersionConflictError, so a handler can react gracefully to
+// losing a race against a concurrent writer on the same aggregate stream
+// (e.g. two idempotent ingest calls for the same dedup key). The append
+// runs inside a driver-native SAVEPOINT: a conflict rolls back only that
+// nested scope, leaving the rest of the handler's transaction usable —
+// unlike unsafeAppendEvent, whose thrown VersionConflictError poisons the
+// entire enclosing transaction.
+export type TryAppendEventResult =
+  | { readonly ok: true; readonly event: import("../../event-store").StoredEvent }
+  | { readonly ok: false; readonly conflict: import("../../event-store").VersionConflictError };
+
+export type TryAppendEventFn = (args: AppendEventArgs) => Promise<TryAppendEventResult>;
+
 // Args for ctx.fetchForWriting — Marten FetchForWriting equivalent. Returns
 // the current stream state + a handle that appends without re-specifying
 // aggregateId/aggregateType. When expectedVersion is provided, the handle

package/src/engine/types/index.ts

@@ -157,6 +157,8 @@ export type {
   RateLimitOption,
   RateLimitPer,
   SessionUser,
+  TryAppendEventFn,
+  TryAppendEventResult,
   UnsafeAppendEventFn,
   WriteEvent,
   WriteHandlerDef,
@@ -243,6 +245,7 @@ export type {
   FormatSpec,
   ListColumnSpec,
   PlatformComponent,
+  ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,
   RowAction,
   RowActionNavigate,

package/src/engine/types/screen.ts

@@ -324,6 +324,39 @@ export type ProjectionListScreenDefinition = {
   readonly access?: AccessRule;
 };
 
+// --- projectionDetail ---
+
+// Read-only counterpart to projectionList — a single-row inspector bound to
+// an EXPLICIT query instead of an entity (`entityEdit` requires `r.entity`,
+// which a direct-write/projection read-model like `jobs`/`sessions` doesn't
+// have — see #255). There is no write path: the renderer forces every field
+// readOnly structurally (not just by convention — see
+// renderer/projection-detail-shim.ts), so no `<entity>:write:...:update`
+// command is ever constructed. `idParam` names the query-payload key the
+// route's row-id is passed under; defaults to "id", but a query handler
+// owned by a different feature may already use a domain-specific param name
+// (e.g. jobs' `detailQuery` expects `runId`) — this lets the primitive bind
+// to it without forcing a handler rename. Extension sections aren't
+// supported (no entity for them to persist against); the boot-validator
+// rejects them.
+export type ProjectionDetailScreenDefinition = {
+  readonly id: string;
+  readonly type: "projectionDetail";
+  readonly query: string;
+  /** Query-payload key for the row-id. Default "id". */
+  readonly idParam?: string;
+  readonly layout: EditLayout;
+  /** Optionaler per-Field-Label-i18n-Key (Field-Name → Key), analog zu
+   *  entityEdit.fieldLabels. Die Pseudo-Entity `__projection-detail__` hat
+   *  keinen natürlichen Field-Namespace — fehlt ein Eintrag, gilt die
+   *  Konvention `<feature>:entity:__projection-detail__:field:<name>`. */
+  readonly fieldLabels?: Readonly<Record<string, string>>;
+  /** Parent list screen (kurze id) für eine "Zurück"-Navigation. */
+  readonly listScreenId?: string;
+  readonly slots?: ScreenSlots;
+  readonly access?: AccessRule;
+};
+
 // --- dashboard ---
 
 // Deklaratives Panel-Grid — Kennzahlen, Verläufe und Kurzlisten ohne
@@ -697,6 +730,7 @@ export type ScreenSlots = {
 export type ScreenDefinition =
   | EntityListScreenDefinition
   | ProjectionListScreenDefinition
+  | ProjectionDetailScreenDefinition
   | DashboardScreenDefinition
   | EntityEditScreenDefinition
   | ActionFormScreenDefinition

package/src/entrypoint/index.ts

@@ -176,27 +176,9 @@ function mergeDispatcherOptions(
   return { ...(caller ?? {}), jobRunner };
 }
 
-// Resolve the observability provider ONCE per entrypoint boot, before any
-// job-runner is built. `buildServer` (api/server.ts) independently falls
-// back to `options.observability ?? createNoopProvider()` and merges
-// tracer/meter into a NEW context object it builds internally — but the
-// job-runner is constructed from the caller's RAW `options.context`
-// *before* buildServer ever runs, so it never saw that merge. Its
-// queue-depth poller only starts `if (context.meter)` with no fallback
-// (unlike the tracer, which has its own `getFallbackTracer()`), so an
-// unset meter silently skipped the poller forever — `/metrics` showed the
-// `kumiko_job_queue_depth` HELP/TYPE header but never a single data line
-// (#1046). Resolving once here and threading it into the job-runner's
-// context fixes the gap. This resolved instance is ONLY used for the
-// job-runner — `buildApiServer`/`buildWorkerServer` still pass the
-// caller's original `options.observability` through unchanged (not this
-// resolved value), because `buildServer` also derives `shouldWrapRedis`
-// from whether `options.observability` was explicitly set — forcing it to
-// an always-defined value here would silently switch every app's Redis
-// client onto the tracer-wrapping Proxy path even with no provider
-// configured. buildServer's own independent Noop fallback is harmless in
-// that case: nothing scrapes `/metrics` without a real provider, so a
-// second, disconnected Noop meter costs nothing.
+// Resolved once for the job-runner's context only — buildServer still gets
+// the caller's original `options.observability` (unresolved) since it
+// derives `shouldWrapRedis` from whether that was explicitly set.
 function resolveObservability(
   observability: ObservabilityProvider | undefined,
 ): ObservabilityProvider {

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

@@ -8,6 +8,7 @@ import type {
   EntityListScreenDefinition,
   FeatureDefinition,
   NavDefinition,
+  ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,
   RowAction,
   ScreenDefinition,
@@ -22,6 +23,9 @@ export const ACTION_FORM_ENTITY = "__action-form__";
 /** Pseudo-entity for configEdit field labels (renderer config-edit-shim). */
 export const CONFIG_EDIT_ENTITY = "__config-edit__";
 
+/** Pseudo-entity for projectionDetail field labels (renderer projection-detail-shim). */
+export const PROJECTION_DETAIL_ENTITY = "__projection-detail__";
+
 export function fieldLabelKey(featureName: string, entityName: string, fieldName: string): string {
   return `${featureName}:entity:${entityName}:field:${fieldName}`;
 }
@@ -201,6 +205,20 @@ export function requiredKeysFromScreen(
       }
       break;
     }
+    case "projectionDetail": {
+      const detail = screen as ProjectionDetailScreenDefinition;
+      for (const section of detail.layout.sections) {
+        if (isExtensionEditSection(section)) continue; // rejected at boot, unreachable here
+        pushKey(out, section.title);
+        for (const f of section.fields) {
+          const fieldName = editFieldName(f);
+          const override = detail.fieldLabels?.[fieldName];
+          if (override !== undefined) pushKey(out, override);
+          else out.add(fieldLabelKey(featureName, PROJECTION_DETAIL_ENTITY, fieldName));
+        }
+      }
+      break;
+    }
     case "custom":
       break;
   }

package/src/pipeline/__tests__/try-append-event.integration.test.ts

@@ -0,0 +1,166 @@
+// Issue #1038 — ctx.tryAppendEvent (savepoint-scoped append).
+//
+// Claims pinned here:
+//   1. Happy path: first append on a fresh aggregate succeeds, returns
+//      { ok: true, event } with the stored event.
+//   2. Non-poisoning: when tryAppendEvent loses a version-conflict race, the
+//      rest of the handler's transaction still commits (a write AFTER the
+//      call in the same handler is not rolled back) — this is the whole
+//      reason the primitive exists over a bare try/catch around
+//      unsafeAppendEvent (Bun.SQL/postgres.js abort the entire begin() on
+//      an uncaught statement error, SQLSTATE 25P02, even if the JS error is
+//      caught).
+//
+// The conflict branch can't be forced deterministically through the public
+// interface — appendDomainEventCore reads the stream version fresh inside
+// itself, so a lone sequential append never conflicts; only two concurrent
+// transactions racing the same version produce the 23505. So claim 2 is
+// tested as an invariant over concurrent writers (looped per house
+// convention for probabilistic tests) rather than by asserting the conflict
+// branch was hit on a specific call — depending on interleaving, Postgres
+// may pick either writer as the winner.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { asRawClient, selectMany } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { createEntity, createTextField, defineFeature } from "../../engine";
+import { loadAggregate } from "../../event-store";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+
+const TAE_AGGREGATE_TYPE = "taeDoc";
+
+// Marker entity — a plain CRUD write issued right after ctx.tryAppendEvent
+// in the same handler/transaction. Its row landing (regardless of whether
+// the append won or lost the race) is the non-poisoning proof.
+const markerEntity = createEntity({
+  table: "tae_markers",
+  fields: {
+    note: createTextField({ required: true }),
+  },
+});
+const markerTable = buildEntityTable("taeMarker", markerEntity);
+const markerExecutor = createEventStoreExecutor(markerTable, markerEntity, {
+  entityName: "taeMarker",
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+const tryAppendFeature = defineFeature("tae", (r) => {
+  r.entity("taeMarker", markerEntity);
+  const appended = r.defineEvent("appended", z.object({ note: z.string() }));
+
+  r.writeHandler(
+    "doc:try-append",
+    z.object({ aggregateId: z.uuid(), note: z.string() }),
+    async (event, ctx) => {
+      const result = await ctx.tryAppendEvent({
+        aggregateId: event.payload.aggregateId,
+        aggregateType: TAE_AGGREGATE_TYPE,
+        type: appended.name,
+        payload: { note: event.payload.note },
+      });
+      // Runs unconditionally — if tryAppendEvent's savepoint failed to
+      // confine the VersionConflictError, this write would fail too
+      // because the whole tx aborted (25P02).
+      const markerCreated = await markerExecutor.create(
+        { note: event.payload.note },
+        event.user,
+        ctx.db,
+      );
+      if (!markerCreated.isSuccess) return markerCreated;
+      return {
+        isSuccess: true as const,
+        data: {
+          ok: result.ok,
+          version: result.ok ? result.event.version : null,
+        },
+      };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [tryAppendFeature] });
+  await unsafeCreateEntityTable(stack.db, markerEntity, "taeMarker");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(
+    `TRUNCATE kumiko_events, "${markerTable.tableName}" RESTART IDENTITY CASCADE`,
+  );
+});
+
+describe("Issue #1038 — ctx.tryAppendEvent", () => {
+  test("happy path: first append on a fresh aggregate returns { ok: true, event }", async () => {
+    const aggregateId = crypto.randomUUID();
+
+    const result = await stack.http.writeOk<{
+      ok: boolean;
+      version: number | null;
+    }>("tae:write:doc:try-append", { aggregateId, note: "hello" }, admin);
+
+    expect(result.ok).toBe(true);
+    expect(result.version).toBe(1);
+
+    const events = await loadAggregate(stack.db, aggregateId, admin.tenantId);
+    expect(events).toHaveLength(1);
+    expect(events[0]?.payload).toEqual({ note: "hello" });
+
+    const markers = await selectMany(stack.db, markerTable);
+    expect(markers).toHaveLength(1);
+  });
+
+  // Probabilistic — looped per house convention (mehrere Durchläufe, z.B.
+  // 20x) since a genuine 23505 race depends on transaction-timing
+  // interleaving that a single run can't force deterministically.
+  const ITERATIONS = 20;
+  const CONCURRENCY = 3;
+
+  test(`non-poisoning invariant holds across ${ITERATIONS} concurrent-writer rounds`, async () => {
+    for (let i = 0; i < ITERATIONS; i++) {
+      const aggregateId = crypto.randomUUID();
+
+      const responses = await Promise.all(
+        Array.from({ length: CONCURRENCY }, (_, n) =>
+          stack.http.write("tae:write:doc:try-append", { aggregateId, note: `writer-${n}` }, admin),
+        ),
+      );
+
+      // No writer's transaction was poisoned by a losing append — every
+      // request completes as a normal 200, never a 500 from an aborted tx.
+      let okCount = 0;
+      for (const res of responses) {
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as { isSuccess: boolean; data: { ok: boolean } };
+        expect(body.isSuccess).toBe(true);
+        if (body.data.ok) okCount++;
+      }
+
+      // One event per successful append — interleaving-independent
+      // invariant. Serialized (non-racing) writers can legitimately all
+      // succeed at different versions; only actual conflicts return
+      // { ok: false }, so events.length must track okCount, not a fixed 1.
+      const events = await loadAggregate(stack.db, aggregateId, admin.tenantId);
+      expect(events).toHaveLength(okCount);
+      expect(okCount).toBeGreaterThanOrEqual(1);
+
+      // Every writer's marker insert landed regardless of win/lose — the
+      // savepoint confined the losers' VersionConflictError instead of
+      // aborting their whole transaction.
+      const markers = await selectMany(stack.db, markerTable);
+      expect(markers).toHaveLength(CONCURRENCY);
+
+      await asRawClient(stack.db).unsafe(
+        `TRUNCATE kumiko_events, "${markerTable.tableName}" RESTART IDENTITY CASCADE`,
+      );
+    }
+  });
+});

package/src/pipeline/dispatch-shared.ts

@@ -1,6 +1,6 @@
 import { requestContext } from "../api/request-context";
-import type { DbConnection, DbTx } from "../db/connection";
-import { selectMany } from "../db/query";
+import type { DbConnection, DbRunner, DbTx } from "../db/connection";
+import { runInSavepoint, selectMany } from "../db/query";
 import type { buildEntityTable } from "../db/table-builder";
 import { createTenantDb } from "../db/tenant-db";
 import type { defineTransitions } from "../engine/state-machine";
@@ -30,6 +30,7 @@ import {
   isStreamArchived,
   restoreStream as restoreStreamHelper,
 } from "../event-store/archive";
+import { VersionConflictError as EventStoreVersionConflictError } from "../event-store/errors";
 import {
   getStreamVersion,
   loadAggregate,
@@ -229,6 +230,42 @@ export function buildHandlerContext(
     unsafeAppendEvent: async (args: AppendEventArgs) => {
       await appendDomainEvent(ctx, args, user, tx, registry.getHandlerFeature(type));
     },
+    // Savepoint-scoped append: catches a losing writer's VersionConflictError
+    // without poisoning the rest of the handler's transaction. Bun.SQL/
+    // postgres.js abort the WHOLE begin() on an uncaught statement error
+    // (SQLSTATE 25P02) even if the JS error is caught — runInSavepoint
+    // wraps the append in a real SAVEPOINT so only that nested scope rolls
+    // back on conflict, and subsequent statements in the outer tx (e.g. a
+    // dedup-anchor insert) still succeed. Use when a handler must react to
+    // losing a concurrent-append race instead of failing the whole write.
+    tryAppendEvent: async (args: AppendEventArgs) => {
+      if (!tx) {
+        throw new InternalError({
+          message: `ctx.tryAppendEvent("${args.type}") requires an active transaction — no tx is threaded through this call.`,
+        });
+      }
+      try {
+        const event = await runInSavepoint(tx, (sp) =>
+          appendDomainEventCore(
+            {
+              registry,
+              db: sp as DbRunner,
+              tenantId: user.tenantId,
+              userId: String(user.id),
+              callSiteLabel: "ctx.tryAppendEvent",
+              callerFeature: registry.getHandlerFeature(type),
+            },
+            args,
+          ),
+        );
+        return { ok: true as const, event };
+      } catch (e) {
+        if (e instanceof EventStoreVersionConflictError) {
+          return { ok: false as const, conflict: e };
+        }
+        throw e;
+      }
+    },
     fetchForWriting: async (args: FetchForWritingArgs): Promise<AggregateStreamHandle> => {
       const dbSource = resolveDbSource(ctx, tx);
       if (!dbSource) {
@@ -483,12 +520,8 @@ export function buildHandlerContext(
     // Propagate the feature-toggle resolver so the lifecycle pipeline,
     // MSP runner, and ctx.hasFeature all pull from the same source.
     ...(effectiveFeatures && { effectiveFeatures }),
-    // Symmetric with job-runner.ts's jobContext: a manual write handler
-    // reaches `ctx.jobRunner.dispatch(...)` the same way a follow-up job
-    // does (bundled jobs feature's trigger.write.ts is the canonical
-    // caller). Was never actually wired here — DispatchContext.jobRunner
-    // only fed the internal afterCommit auto-trigger hook in
-    // executeWriteInner, never the handler-facing ctx (#983).
+    // Lets write handlers call ctx.jobRunner.dispatch(...) directly, same
+    // as a follow-up job would (test-stack.ts wires the matching runner).
     ...(jobRunner && { jobRunner }),
     // ctx.user als Convenience-Alias auf event.user. Der typisch-
     // intuitive Pfad „der Context kennt seinen User" — ohne den

package/src/stack/__tests__/setup-test-stack-jobs.integration.test.ts

@@ -1,24 +1,7 @@
-// Regression test for #983 — a write handler calling `ctx["jobRunner"]
-// .dispatch(...)` directly (the documented pattern, e.g. bundled jobs
-// feature's trigger.write.ts) threw `TypeError: undefined is not an
-// object` under both `setupTestStack` and `runDevApp`, because neither
-// built a JobRunner nor merged one into the dispatcher's context.
-//
-// Two things had to be fixed together (see dispatch-shared.ts and
-// test-stack.ts for the respective commits):
-//   1. `setupTestStack({ jobs: {...} })` now builds a real JobRunner and
-//      merges it into dispatcherOptions — this test's `jobs: {}` opt-in.
-//   2. `buildHandlerContext` (packages/framework/src/pipeline/dispatch-
-//      shared.ts) never spread `DispatchContext.jobRunner` into the
-//      handler-facing ctx at all — a gap that predates this issue and
-//      affects the prod entrypoint too, not just dev/test. Fixed there,
-//      not band-aided into `context:` here — otherwise test/dev would
-//      pass while prod's `ctx.jobRunner` stayed undefined.
-//
-// This test drives the manual-dispatch repro from the issue, not the
-// auto-trigger path (already covered by entrypoint-job-wiring.integration
-// .test.ts) — the two paths read from different context slots and a fix
-// for one doesn't guarantee the other.
+// Drives the manual `ctx.jobRunner.dispatch(...)` path a write handler
+// uses directly — distinct from the auto-trigger path covered by
+// entrypoint-job-wiring.integration.test.ts, which reads a different
+// context slot and isn't guaranteed by this test passing.
 
 import { afterEach, describe, expect, test } from "bun:test";
 import { z } from "zod";

package/src/stack/test-stack.ts

@@ -124,19 +124,14 @@ export type TestStackOptions = {
         sseBroker: import("../api/sse-broker").SseBroker;
         redis: import("ioredis").default;
       }) => import("../api/server").ServerOptions["anonymousAccess"]);
-  /** Opt-in JobRunner wired into ctx.jobRunner (write handlers'
-   *  `ctx.jobRunner.dispatch(...)`) and merged into dispatcherOptions so
-   *  event-triggered jobs enqueue on commit — mirrors the prod entrypoint's
-   *  `buildJobRunnerWithHook`. No-ops when no `r.job(...)` is registered
-   *  anywhere in the mounted features — the bundled `createJobsFeature()`
-   *  (operator UI) is NOT required, matching prod's unconditional build.
-   *  Default `undefined` — enqueuer-only, holds queue-clients for both
-   *  lanes so `ctx.jobRunner.dispatch(...)` routes correctly but starts no
-   *  local consumer/cron-scheduler (avoids double-running `runOnBoot`/cron
-   *  jobs when the caller, e.g. runDevApp, already runs its own consumer
-   *  for that lane). Pass `consumerLane` only when this IS the sole
-   *  consumer (e.g. a test that wants the dispatched job to actually
-   *  execute without a separate runner). */
+  /** Opt-in JobRunner wired into ctx.jobRunner and merged into
+   *  dispatcherOptions so event-triggered jobs enqueue on commit — mirrors
+   *  the prod entrypoint's `buildJobRunnerWithHook`. Unlike prod (which
+   *  always builds one), this only builds a runner when `registry.getAllJobs()`
+   *  is non-empty — a deliberate test-stack-only shortcut, not parity.
+   *  Default `undefined`. Pass `consumerLane` only when this test IS the
+   *  sole consumer (otherwise enqueuer-only, avoiding double-running
+   *  `runOnBoot`/cron jobs against a caller-owned consumer). */
   jobs?: {
     consumerLane?: JobRunIn;
     queueNamePrefix?: string;

package/src/testing/e2e-generator.ts

@@ -115,6 +115,8 @@ export function generateE2ESpec(
     // projectionList: query-getrieben, Author-spezifische Projection —
     // kein generischer CRUD-Spec ableitbar (wie actionForm/configEdit).
     if (screen.type === "projectionList") continue;
+    // projectionDetail: dito — read-only single-row inspector, kein CRUD-Zustand.
+    if (screen.type === "projectionDetail") continue;
     // dashboard: panel-getrieben (Stat/Chart/List-Queries) — dito, keine
     // generische CRUD-Annahme möglich.
     if (screen.type === "dashboard") continue;

package/src/testing/handler-context.ts

@@ -46,6 +46,7 @@ export function bridgeStub(opts?: {
   | "writeAs"
   | "appendEvent"
   | "unsafeAppendEvent"
+  | "tryAppendEvent"
   | "fetchForWriting"
   | "loadAggregate"
   | "archiveStream"
@@ -92,6 +93,7 @@ export function bridgeStub(opts?: {
     unsafeAppendEvent: notAvailable("unsafeAppendEvent") as unknown as (
       args: AppendEventArgs,
     ) => Promise<void>,
+    tryAppendEvent: notAvailable("tryAppendEvent") as unknown as HandlerContext["tryAppendEvent"],
     fetchForWriting: notAvailable("fetchForWriting") as unknown as (
       args: FetchForWritingArgs,
     ) => ReturnType<HandlerContext["fetchForWriting"]>,

package/src/ui-types/index.ts

@@ -67,6 +67,7 @@ export type {
   FieldRenderer,
   ListColumnSpec,
   PlatformComponent,
+  ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,
   RowAction,
   RowActionNavigate,