@cosmicdrift/kumiko-framework 0.146.3 → 0.147.0

package/src/engine/types/screen.ts

@@ -346,7 +346,7 @@ export type DashboardStatPanel = {
   readonly valueField: string;
   readonly subField?: string;
   readonly toneField?: string;
-  /** Optionaler Delta-Chip (z.B. "↓ 23 %") neben dem Label. Nur wenn BEIDE
+  /** Optionaler Delta-Chip (z.B. "↓23 %") neben dem Label. Nur wenn BEIDE
    *  Felder gesetzt sind UND der Query-Handler sie liefert, rendert der Chip
    *  — sonst bleibt die Kachel wie ohne Delta. `deltaToneField` fällt auf
    *  `toneField`/"default" zurück, wenn ungesetzt. */
@@ -361,7 +361,9 @@ export type DashboardStatPanel = {
    *  für ein reines Icon). */
   readonly icon?: PlatformComponent;
   /** Statischer CSS-Farbwert (z.B. "var(--color-debt)") für den Icon-Chip —
-   *  Passthrough an die Kachel, keine Registry, kein Lookup. */
+   *  Passthrough an die Kachel, keine Registry, kein Lookup. Wirkt NUR wenn
+   *  `icon` gesetzt ist (StatCard rendert den Chip nur zusammen mit einem
+   *  Icon) — ohne icon wird der Wert still verworfen. */
   readonly accentColor?: string;
 };
 

package/src/engine/types/tree-node.ts

@@ -1,6 +1,5 @@
-// TreeNode — single Knoten im Visual-Tree (opt-in Workspace mit
-// `navigation: "tree"`). Provider liefern entweder statische
-// readonly TreeNode[] oder dynamische TreeChildrenSubscribe.
+// TreeNode — single Knoten im Client-navProvider-Tree. Provider liefern
+// entweder statische readonly TreeNode[] oder dynamische TreeChildrenSubscribe.
 //
 // **Mental-Modell** (VS-Code-Explorer):
 //   [icon] [label] [...hover-actions]
@@ -20,8 +19,6 @@
 // Emits beliebig oft (z.B. wenn Entity-Row neu erscheint via SSE).
 // Spielt natürlich mit existing SSE-Frame: ein Provider kann intern
 // auf Entity-Update-Events abonnieren und bei Änderung emit() aufrufen.
-//
-// Siehe docs/plans/architecture/visual-tree.md A4.
 
 import type { TargetRef } from "./target-ref";
 

package/src/event-store/snapshot.ts

@@ -209,13 +209,6 @@ export async function loadAggregateWithSnapshot<TState extends Record<string, un
   initial: TState,
   options?: LoadAggregateWithSnapshotOptions,
 ): Promise<LoadAggregateWithSnapshotResult<TState>> {
-  if (!options?.includeArchived) {
-    const archived = await isStreamArchived(db, tenantId, aggregateId);
-    if (archived) {
-      return { state: initial, version: 0, snapshotHit: false };
-    }
-  }
-  const shapeVersion = options?.snapshotVersion ?? 1;
   if (
     options?.snapshotEvery !== undefined &&
     (!Number.isInteger(options.snapshotEvery) || options.snapshotEvery < 1)
@@ -224,6 +217,13 @@ export async function loadAggregateWithSnapshot<TState extends Record<string, un
       `loadAggregateWithSnapshot: snapshotEvery must be an integer >= 1, got ${String(options.snapshotEvery)}`,
     );
   }
+  if (!options?.includeArchived) {
+    const archived = await isStreamArchived(db, tenantId, aggregateId);
+    if (archived) {
+      return { state: initial, version: 0, snapshotHit: false };
+    }
+  }
+  const shapeVersion = options?.snapshotVersion ?? 1;
   const stored = await loadLatestSnapshot<TState>(db, aggregateId, tenantId);
   const snapshot = stored && stored.snapshotVersion === shapeVersion ? stored : null;
   const baseState = snapshot ? snapshot.state : initial;

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

@@ -86,11 +86,13 @@ function pushDashboardPanelKeys(out: Set<string>, panel: DashboardPanelDefinitio
       if (normalized.label !== undefined) pushKey(out, normalized.label);
     }
   }
+  if (panel.kind === "feed" && panel.emptyLabel !== undefined) pushKey(out, panel.emptyLabel);
 }
 
 function pushDashboardFilterKeys(out: Set<string>, filter: DashboardFilterDefinition): void {
   pushKey(out, filter.label);
   if (filter.allLabel !== undefined) pushKey(out, filter.allLabel);
+  if (filter.placeholder !== undefined) pushKey(out, filter.placeholder);
   for (const opt of filter.options ?? []) pushKey(out, opt.label);
 }
 

package/src/jobs/job-runner.ts

@@ -138,7 +138,7 @@ async function startQueueDepthPolling(
 ): Promise<ReturnType<typeof setInterval>> {
   const pollQueueDepth = async (): Promise<void> => {
     try {
-      const counts = await queue.getJobCounts();
+      const counts = await queue.getJobCounts("waiting", "active", "delayed", "failed", "paused");
       emitJobQueueDepth(meter, lane, counts);
     } catch {
       // skip: transient Redis hiccup — next poll retries

package/src/observability/standard-metrics.ts

@@ -227,9 +227,10 @@ 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.
+// counts: BullMQ's Queue.getJobCounts() result, filtered by the caller to
+// backlog-relevant states (waiting/active/delayed/failed/paused) — "completed"
+// grows unboundedly without removeOnComplete and would make the gauge series
+// monotonically increasing, useless as a backlog signal.
 export function emitJobQueueDepth(
   meter: Meter,
   lane: string,

package/src/pipeline/dispatch-batch.ts

@@ -169,9 +169,9 @@ export async function runBatch(
 }
 
 // Unwrap a BatchResult into a single WriteResult for write()/command().
-// Picks the last result if present (the failing one for failures, the only
-// one for successful single writes). Falls back to a synthetic error if the
-// batch didn't produce any results (unexpected).
+// Picks the first result on success (the only one for a single write), the
+// failing one on failure. Falls back to a synthetic error if the batch
+// didn't produce any results (unexpected).
 export function unwrapSingle(batchResult: BatchResult): WriteResult {
   if (batchResult.isSuccess) {
     return (

package/src/pipeline/dispatch-shared.ts

@@ -147,7 +147,7 @@ export function buildHandlerContext(
   afterCommitHooks?: AfterCommitHook[],
   includeDeleted?: boolean,
 ): HandlerContext {
-  const { registry, appContext: context, effectiveFeatures } = ctx;
+  const { registry, appContext: context, effectiveFeatures, jobRunner } = ctx;
   const isSystem = registry.isHandlerSystemScoped(type);
   // The outer dispatcher receives a DbConnection from the server/stack;
   // AppContext's `db` union also allows TenantDb (for downstream hook calls),
@@ -483,6 +483,13 @@ 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).
+    ...(jobRunner && { jobRunner }),
     // ctx.user als Convenience-Alias auf event.user. Der typisch-
     // intuitive Pfad „der Context kennt seinen User" — ohne den
     // schreiben Handler `event.user.tenantId` und brechen sich die
@@ -559,15 +566,6 @@ export async function runHandlerInstrumented<T>(
   }
 }
 
-// L3 rate limit gate. Called by both query and write paths before
-// access-check. Reasoning:
-//   - handler without rateLimit → no-op
-//   - app booted without rateLimit resolver → InternalError so the
-//     misconfig surfaces immediately, not on first 429
-//   - bucket builder returns "skip" (e.g. ip-based but no client IP):
-//     pass through. ip-modes are commonly used at L1/L2 middleware
-//     where the IP comes from Hono directly; falling back to "skip"
-//     here keeps non-HTTP entry-points (jobs, MSPs) functional.
 // Feature-toggle gate. Returns the error to fold into a WriteFailure in the
 // write path, or throws for the query path (where throws flow through the
 // same outer instrumentation wrapper as other dispatcher errors).
@@ -608,6 +606,15 @@ export async function ensureFeatureEnabled(
   if (err) throw err;
 }
 
+// L3 rate limit gate. Called by both query and write paths before
+// access-check. Reasoning:
+//   - handler without rateLimit → no-op
+//   - app booted without rateLimit resolver → InternalError so the
+//     misconfig surfaces immediately, not on first 429
+//   - bucket builder returns "skip" (e.g. ip-based but no client IP):
+//     pass through. ip-modes are commonly used at L1/L2 middleware
+//     where the IP comes from Hono directly; falling back to "skip"
+//     here keeps non-HTTP entry-points (jobs, MSPs) functional.
 export async function enforceRateLimit(
   ctx: DispatchContext,
   rateLimit: import("../engine/types").RateLimitOption | undefined,

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

@@ -0,0 +1,289 @@
+import type { DbConnection, DbTx } from "../db/connection";
+import {
+  advanceConsumerPastEventReturning,
+  updateConsumerStatusReturning,
+} from "../db/queries/event-consumer";
+import { selectNextEventIdAfter } from "../db/queries/event-store";
+import { coerceRow, extractTableInfo, selectMany } from "../db/query";
+import { getEventsHighWaterMark } from "../event-store";
+import { eventConsumerStateTable, SHARED_INSTANCE_SENTINEL } from "./event-consumer-state";
+import type { ConsumerStateRow, ConsumerStateRowShape } from "./event-dispatcher-delivery";
+
+// --- Ops recovery surface ---
+//
+// These are intentionally verb-distinct; each maps to a CLI sub-command.
+// They all target a single consumer row by name. Every call returns the
+// state after the write so the CLI can echo what actually changed.
+//
+// Semantics:
+//   restartConsumer   status="dead" → "idle", attempts=0, lastError=null.
+//                     Cursor unchanged → next pass retries the SAME event
+//                     that poisoned the consumer. For transient failures.
+//   disableConsumer   status=* → "disabled". Dispatcher skips this consumer
+//                     until enableConsumer() flips it back.
+//   enableConsumer    status="disabled" → "idle". No-op on any other state.
+//   skipPoisonEvent   cursor advances past the first event after the
+//                     current cursor (the one that's failing). attempts=0,
+//                     lastError=null, status="idle". For events that will
+//                     never succeed (broken payload, removed feature code).
+
+function normalizeConsumerState(row: ConsumerStateRowShape): ConsumerRecoveryState {
+  return {
+    name: row.name,
+    instanceId: row.instanceId,
+    status: row.status,
+    lastProcessedEventId: row.lastProcessedEventId,
+    attempts: row.attempts,
+    lastError: row.lastError,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export type ConsumerRecoveryState = {
+  readonly name: string;
+  readonly instanceId: string;
+  readonly status: string;
+  readonly lastProcessedEventId: bigint;
+  readonly attempts: number;
+  readonly lastError: string | null;
+  readonly updatedAt: Temporal.Instant;
+};
+
+// Ops calls default to the SHARED_INSTANCE_SENTINEL row — that's the only
+// row shared-delivery consumers have, so legacy CLI invocations without
+// --instance-id keep working. Per-instance consumers require an explicit
+// instanceId: picking one of N shards arbitrarily ("first row wins") or
+// mutating all shards simultaneously ("bounce every instance") are both
+// worse than a loud missing-arg error on the CLI.
+async function requireConsumerRow(
+  db: DbConnection,
+  name: string,
+  instanceId: string,
+): Promise<ConsumerStateRowShape> {
+  const [row] = await selectMany<ConsumerStateRow>(db, eventConsumerStateTable, {
+    name,
+    instanceId,
+  });
+  if (!row) {
+    throw new Error(
+      `Consumer "${name}" (instance_id="${instanceId}") has no state row — it hasn't run yet, the name is misspelled, or the instance is misspelled. ` +
+        `For per-instance consumers pass the instance_id explicitly; shared consumers use the default.`,
+    );
+  }
+  return row;
+}
+
+async function applyConsumerStatusTransition(
+  db: DbConnection,
+  name: string,
+  instanceId: string,
+  targetStatus: "idle" | "disabled",
+): Promise<ConsumerRecoveryState> {
+  const raw = await updateConsumerStatusReturning(db, name, instanceId, targetStatus);
+  const updated =
+    raw && (coerceRow(raw, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow);
+  if (!updated) {
+    throw new Error(
+      `Consumer "${name}" (instance_id="${instanceId}") vanished between read and write — retry.`,
+    );
+  }
+  return normalizeConsumerState(updated);
+}
+
+export async function restartConsumer(
+  db: DbConnection,
+  name: string,
+  instanceId: string = SHARED_INSTANCE_SENTINEL,
+): Promise<ConsumerRecoveryState> {
+  const before = await requireConsumerRow(db, name, instanceId);
+  if (before.status !== "dead") {
+    throw new Error(
+      `Consumer "${name}" (instance_id="${instanceId}") is not dead (status="${before.status}"). Restart only applies to dead consumers; use "enable" for a disabled one.`,
+    );
+  }
+  return applyConsumerStatusTransition(db, name, instanceId, "idle");
+}
+
+export async function disableConsumer(
+  db: DbConnection,
+  name: string,
+  instanceId: string = SHARED_INSTANCE_SENTINEL,
+): Promise<ConsumerRecoveryState> {
+  await requireConsumerRow(db, name, instanceId);
+  return applyConsumerStatusTransition(db, name, instanceId, "disabled");
+}
+
+export async function enableConsumer(
+  db: DbConnection,
+  name: string,
+  instanceId: string = SHARED_INSTANCE_SENTINEL,
+): Promise<ConsumerRecoveryState> {
+  const before = await requireConsumerRow(db, name, instanceId);
+  if (before.status !== "disabled") {
+    throw new Error(
+      `Consumer "${name}" (instance_id="${instanceId}") is not disabled (status="${before.status}"). Enable only flips disabled → idle; use "restart" for a dead consumer.`,
+    );
+  }
+  return applyConsumerStatusTransition(db, name, instanceId, "idle");
+}
+
+// skipPoisonEvent advances the cursor past the first event after the
+// current cursor. Single TX so concurrent dispatcher passes can't double-
+// advance. If no event exists past the cursor, there is nothing to skip —
+// treat as idempotent no-op (cursor already at head).
+export async function skipPoisonEvent(
+  db: DbConnection,
+  name: string,
+  instanceId: string = SHARED_INSTANCE_SENTINEL,
+): Promise<ConsumerRecoveryState & { readonly skippedEventId: bigint | null }> {
+  const before = await requireConsumerRow(db, name, instanceId);
+  return db.begin(async (tx: DbTx) => {
+    const poisonId = await selectNextEventIdAfter(tx, before.lastProcessedEventId);
+    if (poisonId === null) {
+      const [unchanged] = await selectMany<ConsumerStateRow>(tx, eventConsumerStateTable, {
+        name,
+        instanceId,
+      });
+      if (!unchanged)
+        throw new Error(`Consumer "${name}" (instance_id="${instanceId}") vanished — retry.`);
+      return { ...normalizeConsumerState(unchanged), skippedEventId: null };
+    }
+    const raw = await advanceConsumerPastEventReturning(tx, name, instanceId, poisonId);
+    const updated =
+      raw && (coerceRow(raw, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow);
+    if (!updated)
+      throw new Error(
+        `Consumer "${name}" (instance_id="${instanceId}") vanished mid-skip — retry.`,
+      );
+    return { ...normalizeConsumerState(updated), skippedEventId: poisonId };
+  });
+}
+
+// Read-only status for one consumer shard — CLI surface.
+export async function getConsumerState(
+  db: DbConnection,
+  name: string,
+  instanceId: string = SHARED_INSTANCE_SENTINEL,
+): Promise<{
+  readonly name: string;
+  readonly instanceId: string;
+  readonly status: string;
+  readonly lastProcessedEventId: bigint;
+  readonly attempts: number;
+  readonly lastError: string | null;
+  readonly updatedAt: Temporal.Instant;
+} | null> {
+  const [row] = await selectMany<ConsumerStateRow>(db, eventConsumerStateTable, {
+    name,
+    instanceId,
+  });
+  if (!row) return null;
+  return {
+    name: row.name,
+    instanceId: row.instanceId,
+    status: row.status,
+    lastProcessedEventId: row.lastProcessedEventId,
+    attempts: row.attempts,
+    lastError: row.lastError,
+    updatedAt: row.updatedAt,
+  };
+}
+
+// List every consumer the registry knows about, joined with all shard rows
+// from the state table. One entry per (name, instance_id) shard. Consumers
+// that have never run appear with status="never-run" and instance_id =
+// SHARED_INSTANCE_SENTINEL — a placeholder, because without a running
+// dispatcher we can't know the instance-ids of per-instance consumers yet.
+// Mirrors listProjectionsWithState — the registry (not the DB) is the
+// source-of-truth for which consumer-names exist; the DB is the source-
+// of-truth for which instance-shards have been seen.
+export async function listConsumersWithState(
+  db: DbConnection,
+  registeredNames: readonly string[],
+): Promise<
+  ReadonlyArray<{
+    readonly name: string;
+    readonly instanceId: string;
+    readonly status: string;
+    readonly lastProcessedEventId: bigint;
+    readonly attempts: number;
+    readonly lastError: string | null;
+  }>
+> {
+  const stateRows = await selectMany<ConsumerStateRow>(db, eventConsumerStateTable);
+  const registered = new Set(registeredNames);
+
+  // Materialize one output row per (name, instance_id). Registered names
+  // without any shard (never-run) get a placeholder row so ops can still
+  // see the name exists.
+  const out: Array<{
+    name: string;
+    instanceId: string;
+    status: string;
+    lastProcessedEventId: bigint;
+    attempts: number;
+    lastError: string | null;
+  }> = [];
+
+  const seenNames = new Set<string>();
+  for (const r of stateRows) {
+    if (!registered.has(r.name)) continue; // stale row from an older deploy
+    seenNames.add(r.name);
+    out.push({
+      name: r.name,
+      instanceId: r.instanceId,
+      status: r.status,
+      lastProcessedEventId: r.lastProcessedEventId,
+      attempts: r.attempts,
+      lastError: r.lastError,
+    });
+  }
+  for (const name of registeredNames) {
+    if (seenNames.has(name)) continue;
+    out.push({
+      name,
+      instanceId: SHARED_INSTANCE_SENTINEL,
+      status: "never-run",
+      lastProcessedEventId: 0n,
+      attempts: 0,
+      lastError: null,
+    });
+  }
+  return out;
+}
+
+export type ConsumerProgress = {
+  readonly name: string;
+  readonly instanceId: string;
+  readonly status: string;
+  readonly lastProcessedEventId: bigint;
+  readonly attempts: number;
+  readonly lastError: string | null;
+  // Global MAX(events.id) at query time.
+  readonly highWaterMark: bigint;
+  // HWM - cursor. 0n when caught-up. Disabled consumers often show high
+  // lag intentionally (ops parks them before pruning).
+  readonly lag: bigint;
+};
+
+// Like listConsumersWithState, but also returns HWM + lag per consumer.
+// Async consumers (MSPs) lag behind inline projections because they run
+// post-commit — lag is the primary signal for backpressure, dead consumers,
+// or dispatcher stalls. Programmatic callers can map the result to a
+// `kumiko_consumer_lag{name}` Prometheus gauge.
+// guard:dup-ok — intentionale Parallele zu getAllProjectionProgress; Consumer ≠ Projection (verschiedene Subsysteme)
+export async function getAllConsumerProgress(
+  db: DbConnection,
+  registeredNames: readonly string[],
+): Promise<readonly ConsumerProgress[]> {
+  const [consumers, highWaterMark] = await Promise.all([
+    listConsumersWithState(db, registeredNames),
+    getEventsHighWaterMark(db),
+  ]);
+
+  return consumers.map((c) => ({
+    ...c,
+    highWaterMark,
+    lag: highWaterMark - c.lastProcessedEventId,
+  }));
+}