@cosmicdrift/kumiko-framework 0.132.0 → 0.134.0

package/src/engine/types/feature.ts

@@ -70,7 +70,7 @@ import type {
 } from "./projection";
 import type { EntityRelations, RelationDefinition } from "./relations";
 import type { ScreenDefinition } from "./screen";
-import type { TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe } from "./tree-node";
+import type { TreeActionDef, TreeActionsHandle } from "./tree-node";
 import type { WorkspaceDefinition } from "./workspace";
 
 // --- Metrics (declared by features via r.metric()) ---
@@ -352,13 +352,6 @@ export type FeatureDefinition = {
   // feature exports via setup-return — buildTarget consumes the handle,
   // not this slot. See visual-tree.md A5 + A7.
   readonly treeActions?: Readonly<Record<string, TreeActionDef>>;
-  // Tree-Provider declared via r.tree(). At-most-one per feature.
-  // Provider liefert die Top-Level-Knoten dieses Features im Visual-
-  // Workspace (navigation: "tree"). Subscribe-Form mit lazy-Eval: erst
-  // beim Mount des Workspaces aufgerufen, kann Updates emittieren.
-  // Feature ohne treeProvider ist im Visual-Workspace unsichtbar
-  // (Zero-Whitelist-Filter aus visual-tree.md A2).
-  readonly treeProvider?: TreeChildrenSubscribe;
   // HTTP-Routes declared via r.httpRoute(). Index is "METHOD path"
   // (z.B. "GET /feed.xml") — eindeutig pro Feature. Die App-Server-
   // Boot-Stage iteriert getAllHttpRoutes() und mountet jede Route auf
@@ -771,20 +764,6 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // k8s-secret hints) goes into `.meta({ kumiko: { pulumi: {...} } })`
   // — see framework/env/index.ts for the meta-shape.
   envSchema(schema: z.ZodObject<z.ZodRawShape>): void;
-
-  // Register the tree-provider for this feature — the Subscribe-Function
-  // that emits the top-level Tree-Knoten when the Visual-Workspace
-  // (navigation: "tree") mounts. At-most-one call per feature.
-  //
-  // Provider returns a Subscribe-Function (emit-fn → unsubscribe-fn).
-  // Initial-emit synchron oder async, weitere Emits beliebig oft (e.g.
-  // on entity-update SSE). Provider sind session-bound; tenantId fließt
-  // über die Backend-Session bei fetch/dispatch, nicht über ein ctx-Arg.
-  //
-  // A feature without r.tree() is invisible in `navigation: "tree"`-
-  // workspaces — that's the Zero-Whitelist-Filter from visual-tree.md A2:
-  // provider-Vorhandensein ist der Filter, kein Workspace-Mapping.
-  tree(provider: TreeChildrenSubscribe): void;
 };
 
 // --- Registry (created from features) ---
@@ -977,18 +956,9 @@ export type Registry = {
   // the first workspace the user has access to.
   getDefaultWorkspace(): WorkspaceDefinition | undefined;
 
-  // Tree-Providers declared via r.tree() across all features. Keyed by
-  // declaring feature name (NOT qualified — Provider sind feature-bound,
-  // ein Feature liefert genau eine Provider-Function). The Visual-Tree
-  // component (renderer-web) iteriert getTreeProviders() beim Mount des
-  // navigation: "tree"-Workspaces, ruft jeden Provider mit ctx auf,
-  // sammelt die emitted TreeNode[] und merged sie zur Top-Level-Liste.
-  // See visual-tree.md A2 (Zero-Whitelist) + A4 (Subscribe-Form).
-  getTreeProviders(): ReadonlyMap<string, TreeChildrenSubscribe>;
-
   // Tree-Actions-Map des Features. Returns the erased Record (compile-
-  // time-typed handle wandert über setup-export, nicht hier). Visual-
-  // Tree-Component nutzt das für Runtime-Action-Lookup beim Klick auf
+  // time-typed handle wandert über setup-export, nicht hier). Die
+  // Content-Tree-Nav nutzt das für Runtime-Action-Lookup beim Klick auf
   // einen TreeNode.target — der Resolver findet das Feature via
   // TargetRef.featureId und holt sich die zugehörige Action-Definition.
   getTreeActions(featureName: string): Readonly<Record<string, TreeActionDef>> | undefined;

package/src/engine/types/fields.ts

@@ -354,7 +354,7 @@ export type JsonbFieldDef = {
 // Legacy "date" — JS-Date-Object, semantisch unklar (Wall-Clock vs Instant).
 // Für neue Felder bevorzuge:
 //   - `timestamp` für UTC-Instant ("wann ist das passiert")
-//   - `locatedTimestamp(name)` Helper für Termine die an einem Ort
+//   - `createLocatedTimestampField()` für Termine die an einem Ort
 //     stattfinden ("Pickup um 10:00 in Lissabon")
 //   - (kommt) `plainDate` für Kalender-Daten ohne Uhrzeit (z.B. Geburtstag)
 // Siehe docs/plans/architecture/timezones.md
@@ -384,8 +384,8 @@ export type DateFieldDef = {
 // speichert Wall-Clock+tz und konvertiert transparent (siehe DB-Wrapper,
 // kommt in einer späteren Iteration).
 //
-// Verwendung über den `locatedTimestamp(name)` Helper, der das Pair atomar
-// erzeugt und die Marker korrekt verdrahtet.
+// Für neue Felder bevorzuge `createLocatedTimestampField()` — EIN atomares
+// Feld statt eines lose verdrahteten Pairs (siehe LocatedTimestampFieldDef).
 export type TimestampFieldDef = {
   readonly type: "timestamp";
   readonly required?: boolean;
@@ -397,8 +397,9 @@ export type TimestampFieldDef = {
    * Marker: dieses Timestamp-Feld ist Wall-Clock-Zeit an einem Ort.
    * Wert ist der Name des begleitenden tz-Felds (IANA-Zone).
    *
-   * Beispiel: `locatedTimestamp("pickup")` erzeugt
+   * Beispiel: manuelles Pair
    *   { pickupAt: { type: "timestamp", locatedBy: "pickupTz" }, pickupTz: { type: "tz" } }
+   * — bevorzuge stattdessen `createLocatedTimestampField()`.
    */
   readonly locatedBy?: string;
   /** Erlaubte Grenzen als ISO-Datetime. Begrenzt den Picker auf

package/src/engine/types/index.ts

@@ -220,9 +220,14 @@ export type {
   CustomScreenDefinition,
   CustomScreenRoute,
   DashboardChartPanel,
+  DashboardCustomPanel,
+  DashboardFeedPanel,
+  DashboardFilterDefinition,
   DashboardListPanel,
   DashboardPanelDefinition,
+  DashboardProgressListPanel,
   DashboardScreenDefinition,
+  DashboardStatGroupPanel,
   DashboardStatPanel,
   EditExtensionSection,
   EditFieldSpec,

package/src/engine/types/screen.ts

@@ -369,15 +369,78 @@ export type DashboardListPanel = {
   readonly columns: readonly ListColumnSpec[];
 };
 
+// Betitelte Sektion aus mehreren Stat-Panels (z.B. "Net Worth": Assets/Debts/
+// Net). Ein Nesting-Level, kein Group-of-Groups — jedes Kind bleibt ein
+// vollwertiges DashboardStatPanel mit eigener Query/id/label, der Renderer
+// zieht sie nur gemeinsam unter einen Sektions-Titel.
+export type DashboardStatGroupPanel = {
+  readonly kind: "stat-group";
+  readonly id: string;
+  readonly label: string;
+  readonly stats: readonly DashboardStatPanel[];
+};
+
+// Nicht-tabellarische Kurzliste (z.B. "nächste Termine"). Query-Result-
+// Contract: `{ rows: { primary: string; trailing?: string }[] }`.
+export type DashboardFeedPanel = {
+  readonly kind: "feed";
+  readonly id: string;
+  readonly label: string;
+  readonly query: string;
+  readonly emptyLabel?: string;
+};
+
+// Liste aus Label/Wert/Fortschrittsbalken (z.B. Tilgungsfortschritt pro
+// Kredit). Query-Result-Contract: `{ rows: { label: string; value: string;
+// fraction: number }[] }` — fraction wird auf 0..1 geclampt.
+export type DashboardProgressListPanel = {
+  readonly kind: "progress-list";
+  readonly id: string;
+  readonly label: string;
+  readonly query: string;
+};
+
+// Eingehängte App-Komponente, die ihre Daten/Titel selbst verwaltet (wie ein
+// custom Screen, nur als Panel — bleibt an ihrer Array-Position statt in
+// einen separaten Slot zu wandern). Kein `query`, keine `label`: der Renderer
+// löst `component` über dieselbe extensionSectionComponents-Registry auf wie
+// entityEdit-Extension-Sections und List-Header-Slots.
+export type DashboardCustomPanel = {
+  readonly kind: "custom";
+  readonly id: string;
+  readonly component: PlatformComponent;
+};
+
 export type DashboardPanelDefinition =
   | DashboardStatPanel
+  | DashboardStatGroupPanel
   | DashboardChartPanel
-  | DashboardListPanel;
+  | DashboardListPanel
+  | DashboardFeedPanel
+  | DashboardProgressListPanel
+  | DashboardCustomPanel;
+
+// Screen-weiter Picker (Combobox), dessen gewählter Wert unter `id` in JEDE
+// Panel-Query dieses Screens gemerged wird (Query-Handler validieren den Wert
+// selbst gegen die Tenant-Sicht — dies ist UX-Scoping, keine Access-Boundary).
+// Genau eins von `options`/`optionsQuery` ist gesetzt (Boot-Validator prüft).
+export type DashboardFilterDefinition = {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: "select";
+  readonly placeholder?: string;
+  /** i18n-Key für den "(alle)"-Eintrag. */
+  readonly allLabel?: string;
+  readonly options?: readonly { readonly value: string; readonly label: string }[];
+  /** Query-Result-Contract: `{ rows: { value: string; label: string }[] }`. */
+  readonly optionsQuery?: string;
+};
 
 export type DashboardScreenDefinition = {
   readonly id: string;
   readonly type: "dashboard";
   readonly panels: readonly DashboardPanelDefinition[];
+  readonly filter?: DashboardFilterDefinition;
   readonly slots?: ScreenSlots;
   readonly access?: AccessRule;
 };

package/src/engine/types/workspace.ts

@@ -39,11 +39,4 @@ export type WorkspaceDefinition = {
   // Default workspace at login when the user has access to multiple. Boot
   // validator rejects more than one default per app.
   readonly default?: boolean;
-  // Render mode of the workspace's sidebar. "nav" (default, missing-ok)
-  // mounts the existing NavTree component as before. "tree" mounts the
-  // Visual-Tree component which collects r.tree() providers across all
-  // active features. Default-on-undefined preserves backwards-compat —
-  // every existing workspace stays nav-mode without code touch.
-  // See visual-tree.md A1.
-  readonly navigation?: "nav" | "tree";
 };

package/src/errors/classes.ts

@@ -2,7 +2,7 @@ import { toSnakeCase } from "../utils/case";
 import type { FieldIssue } from "./field-issue";
 import { type ErrorOpts, KumikoError } from "./kumiko-error";
 
-export type { FieldIssue, ValidationFieldIssue } from "./field-issue";
+export type { FieldIssue } from "./field-issue";
 
 export type ValidationDetails = {
   readonly fields: readonly FieldIssue[];

package/src/errors/field-issue.ts

@@ -6,6 +6,3 @@ export type FieldIssue = {
   readonly i18nKey: string;
   readonly params?: Readonly<Record<string, unknown>>;
 };
-
-/** @deprecated Use `FieldIssue` — kept for existing imports. */
-export type ValidationFieldIssue = FieldIssue;

package/src/errors/index.ts

@@ -7,7 +7,6 @@ export type {
   UniqueViolationDetails,
   UnprocessableOpts,
   ValidationDetails,
-  ValidationFieldIssue,
   VersionConflictDetails,
 } from "./classes";
 export {

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

@@ -1,6 +1,8 @@
 import type {
   ActionFormScreenDefinition,
   ConfigEditScreenDefinition,
+  DashboardFilterDefinition,
+  DashboardPanelDefinition,
   DashboardScreenDefinition,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
@@ -66,6 +68,32 @@ function pushRowActionKeys(out: Set<string>, action: RowAction): void {
   }
 }
 
+function pushDashboardScreenKeys(out: Set<string>, dashboard: DashboardScreenDefinition): void {
+  for (const panel of dashboard.panels) pushDashboardPanelKeys(out, panel);
+  if (dashboard.filter !== undefined) pushDashboardFilterKeys(out, dashboard.filter);
+}
+
+function pushDashboardPanelKeys(out: Set<string>, panel: DashboardPanelDefinition): void {
+  // skip: custom-Panel übersetzt sich selbst, kein Key hier
+  if (panel.kind === "custom") return;
+  pushKey(out, panel.label);
+  if (panel.kind === "stat-group") {
+    for (const stat of panel.stats) pushKey(out, stat.label);
+  }
+  if (panel.kind === "list") {
+    for (const col of panel.columns) {
+      const normalized = normalizeListColumn(col);
+      if (normalized.label !== undefined) pushKey(out, normalized.label);
+    }
+  }
+}
+
+function pushDashboardFilterKeys(out: Set<string>, filter: DashboardFilterDefinition): void {
+  pushKey(out, filter.label);
+  if (filter.allLabel !== undefined) pushKey(out, filter.allLabel);
+  for (const opt of filter.options ?? []) pushKey(out, opt.label);
+}
+
 function pushToolbarActionKeys(out: Set<string>, action: ToolbarAction): void {
   pushKey(out, action.label);
   if (action.kind === "writeHandler") {
@@ -108,16 +136,7 @@ export function requiredKeysFromScreen(
       break;
     }
     case "dashboard": {
-      const dashboard = screen as DashboardScreenDefinition;
-      for (const panel of dashboard.panels) {
-        pushKey(out, panel.label);
-        if (panel.kind === "list") {
-          for (const col of panel.columns) {
-            const normalized = normalizeListColumn(col);
-            if (normalized.label !== undefined) pushKey(out, normalized.label);
-          }
-        }
-      }
+      pushDashboardScreenKeys(out, screen as DashboardScreenDefinition);
       break;
     }
     case "entityEdit": {

package/src/jobs/__tests__/job-queue-depth.integration.test.ts

@@ -0,0 +1,82 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createRegistry, defineFeature } from "../../engine";
+import type { AppContext, Registry } from "../../engine/types";
+import { createPrometheusMeter, registerStandardMetrics } from "../../observability";
+import { createTestRedis, type TestRedis } from "../../stack";
+import { sleep } from "../../testing";
+import { createJobRunner } from "../job-runner";
+
+let testRedis: TestRedis;
+let redisUrl: string;
+
+const testFeature = defineFeature("test-queue-depth", (r) => {
+  r.job("noop", { trigger: { manual: true } }, async () => {});
+});
+
+beforeAll(async () => {
+  testRedis = await createTestRedis();
+  redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+});
+
+afterAll(async () => {
+  await testRedis.cleanup();
+});
+
+describe("job-runner — kumiko_job_queue_depth", () => {
+  test("start() polls BullMQ counts into the gauge, stop() tears the poller down", async () => {
+    const registry: Registry = createRegistry([testFeature]);
+    const meter = createPrometheusMeter();
+    registerStandardMetrics(meter);
+    const context: AppContext = { meter };
+    const queueNamePrefix = `kumiko-test-qd-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const runner = createJobRunner({
+      registry,
+      context,
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix,
+    });
+
+    try {
+      await runner.start();
+
+      const snapshot = meter.snapshot().get("kumiko_job_queue_depth");
+      expect(snapshot).toBeDefined();
+      const waitingSlot = snapshot?.slots.find(
+        (s) => s.labels?.["lane"] === "worker" && s.labels?.["state"] === "waiting",
+      );
+      expect(waitingSlot).toBeDefined();
+      expect((waitingSlot as { value: number }).value).toBe(0);
+      // BullMQ's fresh Worker connection is still settling right after
+      // start() returns (no boot/cron job here to have already warmed it
+      // up, unlike every other scenario in this suite) — stop() immediately
+      // after start() races the Worker's own connection teardown and throws
+      // an unrelated "Connection is closed" from ioredis. Production runners
+      // live far longer than this; the race is a test-only artifact of
+      // start()+stop() with zero work in between.
+      await sleep(50);
+    } finally {
+      await runner.stop();
+      const keys = await testRedis.redis.keys(`bull:${queueNamePrefix}-worker:*`);
+      if (keys.length > 0) await testRedis.redis.del(...keys);
+    }
+  });
+
+  test("enqueuer-only runner (no consumerLane) never polls — no gauge slots", async () => {
+    const registry: Registry = createRegistry([testFeature]);
+    const meter = createPrometheusMeter();
+    registerStandardMetrics(meter);
+    const context: AppContext = { meter };
+    const queueNamePrefix = `kumiko-test-qd-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const runner = createJobRunner({ registry, context, redisUrl, queueNamePrefix });
+    try {
+      await runner.start();
+      const snapshot = meter.snapshot().get("kumiko_job_queue_depth");
+      expect(snapshot?.slots.length ?? 0).toBe(0);
+    } finally {
+      await runner.stop();
+    }
+  });
+});

package/src/jobs/job-runner.ts

@@ -11,7 +11,13 @@ import {
   SYSTEM_TENANT_ID,
 } from "../engine/types";
 import type { Logger } from "../logging/types";
-import { getFallbackTracer, type SerializedTraceContext, type Tracer } from "../observability";
+import {
+  emitJobQueueDepth,
+  getFallbackTracer,
+  type Meter,
+  type SerializedTraceContext,
+  type Tracer,
+} from "../observability";
 import { createDistributedLock, type DistributedLock } from "../pipeline/distributed-lock";
 import { RedisKeys } from "../pipeline/redis-keys";
 
@@ -119,6 +125,29 @@ function captureTraceContext(tracer: Tracer): SerializedTraceContext | undefined
   return { traceId: span.traceId, spanId: span.spanId };
 }
 
+const QUEUE_DEPTH_POLL_INTERVAL_MS = 15_000;
+
+// kumiko_job_queue_depth: only the lane's own consumer polls — the count is
+// a global Redis-backed value (BullMQ, not per-process), so one reporter per
+// lane is enough. Fires once immediately (metrics exist before the first
+// poll tick) then on an interval; the caller stores + clears the handle.
+async function startQueueDepthPolling(
+  queue: Queue,
+  lane: JobRunIn,
+  meter: Meter,
+): Promise<ReturnType<typeof setInterval>> {
+  const pollQueueDepth = async (): Promise<void> => {
+    try {
+      const counts = await queue.getJobCounts();
+      emitJobQueueDepth(meter, lane, counts);
+    } catch {
+      // skip: transient Redis hiccup — next poll retries
+    }
+  };
+  await pollQueueDepth();
+  return setInterval(() => void pollQueueDepth(), QUEUE_DEPTH_POLL_INTERVAL_MS);
+}
+
 function parseRedisOpts(url: string): { host: string; port: number; db?: number | undefined } {
   const parsed = new URL(url);
   const result: { host: string; port: number; db?: number | undefined } = {
@@ -181,6 +210,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     worker: new Queue(queueNameFor(queueNamePrefix, "worker"), { connection: redisOpts }),
   };
   let worker: Worker | null = null;
+  let queueDepthTimer: ReturnType<typeof setInterval> | null = null;
   // Forward reference to the runner's own API, exposed on the job-handler ctx
   // so a handler can dispatch a follow-up job (job→job chaining, e.g.
   // delivery.render → delivery.send). Assigned just before return; reads happen
@@ -431,9 +461,19 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
           await consumerQueue.add(bootName, {}, { jobId: `boot-${name.replace(/\./g, "-")}` });
         }
       }
+
+      // Skipped when no meter is wired (context.meter is optional, e.g. in
+      // tests without an observability provider).
+      if (context.meter) {
+        queueDepthTimer = await startQueueDepthPolling(consumerQueue, consumerLane, context.meter);
+      }
     },
 
     async stop(): Promise<void> {
+      if (queueDepthTimer) {
+        clearInterval(queueDepthTimer);
+        queueDepthTimer = null;
+      }
       if (worker) {
         await worker.close();
         worker = null;

package/src/observability/__tests__/recording-tracer.test.ts

@@ -87,11 +87,13 @@ describe("RecordingTracer", () => {
     expect(recorded).toHaveLength(1);
   });
 
-  it("startSpanFromContext continues an upstream trace", () => {
+  it("startSpan with parent context continues an upstream trace", () => {
     const { tracer, recorded } = makeTracer();
-    const span = tracer.startSpanFromContext("child", {
-      traceId: "aabbccddeeff00112233445566778899",
-      spanId: "1122334455667788",
+    const span = tracer.startSpan("child", {
+      parent: {
+        traceId: "aabbccddeeff00112233445566778899",
+        spanId: "1122334455667788",
+      },
     });
     span.end();
     expect(recorded[0]?.traceId).toBe("aabbccddeeff00112233445566778899");

package/src/observability/index.ts

@@ -52,6 +52,7 @@ export {
   emitEventConsumerPassOutcome,
   emitEventDispatcherListenConnected,
   emitHttpRequest,
+  emitJobQueueDepth,
   registerStandardMetrics,
   STANDARD_METRIC_DEFS,
 } from "./standard-metrics";

package/src/observability/noop-provider.ts

@@ -5,7 +5,6 @@ import type {
   Meter,
   MetricDefinition,
   ObservabilityProvider,
-  SerializedTraceContext,
   Span,
   SpanStatus,
   StartSpanOptions,
@@ -68,14 +67,6 @@ class NoopTracer implements Tracer {
   getActiveSpan(): Span | undefined {
     return undefined;
   }
-
-  startSpanFromContext(
-    name: string,
-    _context: SerializedTraceContext,
-    _options?: StartSpanOptions,
-  ): Span {
-    return new NoopSpan(name, undefined);
-  }
 }
 
 class NoopCounter implements Counter {

package/src/observability/recording-tracer.ts

@@ -175,18 +175,6 @@ export class RecordingTracer implements Tracer {
   getActiveSpan(): Span | undefined {
     return observabilityContext.getActiveSpan();
   }
-
-  /**
-   * @deprecated Prefer `startSpan(name, { parent: context })`. Retained as a
-   *   thin alias for call-sites that pre-date the unified StartSpanOptions.
-   */
-  startSpanFromContext(
-    name: string,
-    context: SerializedTraceContext,
-    options?: StartSpanOptions,
-  ): Span {
-    return this.startSpan(name, { ...options, parent: context });
-  }
 }
 
 // Helper to serialize an active Span into the cross-process format.

package/src/observability/standard-metrics.ts

@@ -94,6 +94,21 @@ export const STANDARD_METRIC_DEFS: readonly MetricDefinition[] = [
       "1 if the event-dispatcher holds an active PG LISTEN subscription on the events channel, 0 otherwise.",
     labels: [],
   },
+  // BullMQ backlog per lane + state (waiting/active/delayed/failed/…). Only
+  // the process that owns a lane's consumerLane polls it (job-runner.ts
+  // start()) — the count is a global Redis-backed value, no per-instance
+  // label needed. A growing "waiting" count means the lane's worker can't
+  // keep up with dispatch; "failed" trending up means jobs are erroring
+  // silently. Motivated by apps that run every job on the "api" lane
+  // (no dedicated worker consumer) — fanout/reconcile jobs then share
+  // Redis-queue capacity with request-handling, and contention is
+  // otherwise invisible until requests slow down.
+  {
+    name: "kumiko_job_queue_depth",
+    type: "gauge",
+    description: "BullMQ job counts per lane and state.",
+    labels: ["lane", "state"],
+  },
 ] as const;
 
 export function registerStandardMetrics(meter: Meter): void {
@@ -211,3 +226,16 @@ export function emitEventConsumerPassOutcome(
     });
   }
 }
+
+// counts: BullMQ's Queue.getJobCounts() result — a state → count record
+// (waiting/active/delayed/failed/completed/…), passed through unmodified so
+// this stays agnostic of exactly which states BullMQ reports.
+export function emitJobQueueDepth(
+  meter: Meter,
+  lane: string,
+  counts: Readonly<Record<string, number>>,
+): void {
+  for (const [state, count] of Object.entries(counts)) {
+    meter.gauge("kumiko_job_queue_depth").set(count, { lane, state });
+  }
+}

package/src/observability/types/span.ts

@@ -55,10 +55,4 @@ export interface Tracer {
   ): Promise<T>;
   // Current active span from AsyncLocalStorage, or undefined.
   getActiveSpan(): Span | undefined;
-  // @deprecated Prefer `startSpan(name, { parent: context })`.
-  startSpanFromContext(
-    name: string,
-    context: SerializedTraceContext,
-    options?: StartSpanOptions,
-  ): Span;
 }

package/src/pipeline/projection-rebuild.ts

@@ -8,6 +8,7 @@ import {
 } from "../db/queries/projection-rebuild";
 import {
   assertLiveColumnsMatchMeta,
+  assertNoUnreachableLiveRows,
   buildShadowTable,
   ensureRebuildSchema,
   fenceLiveTable,
@@ -326,6 +327,12 @@ export async function rebuildProjection(
       if (skipped.length > 0) {
         await recordRebuildDeadLetters(tx, projectionName, skipped);
       }
+      // 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.
+      if (projection.isImplicit === true) {
+        await assertNoUnreachableLiveRows(tx, projectionName, meta.tableName, sourcesList);
+      }
       await finalizeProjectionRebuild(tx, projectionName, lastProcessedEventId);
       await swapShadowIntoLive(tx, meta.tableName);
     });

package/src/time/tz-context.ts

@@ -17,7 +17,7 @@
 import type { GeoAddress, GeoCoordinates, GeoTzProvider } from "./geo-tz";
 import { ensureTemporalPolyfill, getTemporal } from "./polyfill";
 
-// JSON-Form für Wall-Clock+TZ — siehe locatedTimestamp(name) Helper in
+// JSON-Form für Wall-Clock+TZ — siehe createLocatedTimestampField() in
 // engine/factories.ts. Zwei Felder, idiotensicher.
 export type LocatedTimestampJson = {
   /** Wall-Clock-ISO ohne Offset, z.B. "2026-04-03T10:00:00" */

package/src/ui-types/index.ts

@@ -47,9 +47,14 @@ export type {
   CustomScreenDefinition,
   CustomScreenRoute,
   DashboardChartPanel,
+  DashboardCustomPanel,
+  DashboardFeedPanel,
+  DashboardFilterDefinition,
   DashboardListPanel,
   DashboardPanelDefinition,
+  DashboardProgressListPanel,
   DashboardScreenDefinition,
+  DashboardStatGroupPanel,
   DashboardStatPanel,
   EditExtensionSection,
   EditFieldSpec,

package/src/bun-db/__tests__/bun-test-stack.ts

@@ -1,6 +0,0 @@
-// Provider-agnostic Test-Stack — re-exported from stack/test-stack.ts.
-// setupBunTestStack / BunTestStack sind Aliase für setupTestStack / TestStack.
-// "Bun" ist historisch, jetzt provider-neutral (DB_PROVIDER env).
-
-export type { TestStack as BunTestStack } from "../../stack/test-stack";
-export { setupTestStack as setupBunTestStack } from "../../stack/test-stack";

package/src/db/row-helpers.ts

@@ -1,4 +0,0 @@
-// Legacy re-export shim — fetchOne lebt jetzt in src/bun-db/query.ts.
-
-export type { WhereObject } from "../db/query";
-export { fetchOne } from "../db/query";