@cosmicdrift/kumiko-framework 0.146.2 → 0.146.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.146.2",
+  "version": "0.146.3",
   "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>",
@@ -189,7 +189,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.146.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.146.3",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/pipeline/dispatch-batch.ts

@@ -0,0 +1,187 @@
+import type { DbConnection } from "../db/connection";
+import { transaction } from "../db/query";
+import type { DeleteContext, SaveContext, SessionUser, WriteResult } from "../engine/types";
+import { InternalError, toWriteErrorInfo, writeFailure } from "../errors";
+import { createFallbackLogger } from "../logging/utils";
+import { parseJsonSafe } from "../utils/safe-json";
+import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shared";
+import { resolveDbSource } from "./dispatch-shared";
+import { executeNestedWrite } from "./dispatch-write";
+import {
+  type AfterCommitHook,
+  BatchRollback,
+  isLifecycleResult,
+  wrapToKumiko,
+} from "./dispatcher-utils";
+
+// Core batch logic extracted so write() and command() can reuse it
+// (a single write = batch of one, running in its own transaction).
+export async function runBatch(
+  ctx: DispatchContext,
+  commands: readonly BatchCommand[],
+  user: SessionUser,
+  requestId?: string,
+): Promise<BatchResult> {
+  const { idempotency, lifecycle, appContext: context } = ctx;
+  if (commands.length === 0) {
+    return { isSuccess: true, results: [] };
+  }
+
+  // Idempotency: if the same requestId has already been processed, return the
+  // cached result without re-executing. The cache holds the full BatchResult.
+  if (requestId && idempotency) {
+    const cached = await idempotency.check(requestId);
+    if (cached) {
+      const parsed = parseJsonSafe<BatchResult | null>(cached, null);
+      if (parsed) return parsed;
+      // corrupted cache entry — treat as miss, let the request re-run
+    }
+  }
+
+  // Wrap return paths: cache the final result under requestId so retries get
+  // the same answer (both success and failure results are cached).
+  const finalize = async (result: BatchResult): Promise<BatchResult> => {
+    if (requestId && idempotency) {
+      await idempotency.store(requestId, result);
+    }
+    return result;
+  };
+
+  const afterCommitHooks: AfterCommitHook[] = [];
+  const results: WriteResult[] = [];
+
+  // Flush afterCommit hooks in parallel. Errors are logged, not rethrown:
+  // the writes are already committed, we can't undo them.
+  //
+  // Parallelisation is safe because afterCommit hooks are deferred side-
+  // effects (e.g. feature-level postSave hooks in afterCommit phase)
+  // that don't depend on each other — the in-transaction work already ran
+  // sequentially inside the lifecycle pipeline where ordering matters. If a
+  // future hook ever needs ordering, it should do its sequencing internally
+  // (one hook pushing multiple sub-calls) rather than relying on the
+  // flush-loop order.
+  const flushAfterCommit = async () => {
+    const logError = createFallbackLogger("dispatcher", context.log);
+    const outcomes = await Promise.allSettled(afterCommitHooks.map((hook) => hook()));
+    for (const outcome of outcomes) {
+      if (outcome.status === "rejected") {
+        const detail =
+          outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+        logError.error("afterCommit hook failed", { error: detail });
+      }
+    }
+  };
+
+  // Fires the batch-level system hooks with every successful save/delete
+  // context from this run. Called after flushAfterCommit so per-save hooks
+  // have all completed first; errors are isolated inside lifecycleHooks.
+  const flushBatchHooks = async () => {
+    try {
+      const saves: SaveContext[] = [];
+      const deletes: DeleteContext[] = [];
+      for (const r of results) {
+        if (!r.isSuccess) continue;
+        if (!isLifecycleResult(r.data)) continue;
+        if (r.data.kind === "save") saves.push(r.data);
+        else if (r.data.kind === "delete") deletes.push(r.data);
+      }
+      if (saves.length > 0 && lifecycle) await lifecycle.runPostSaveBatch(saves, context);
+      if (deletes.length > 0 && lifecycle) await lifecycle.runPostDeleteBatch(deletes, context);
+    } catch (e) {
+      // Batch hooks must never fail the batch — the commit already happened.
+      // Pass the raw error so the logger preserves stack + cause chain;
+      // collapsing to .message hides exactly what ops needs to debug.
+      const logError = createFallbackLogger("dispatcher", context.log);
+      logError.error("batch hook flush failed", { error: e });
+    }
+  };
+
+  // batch() opens its own outer transaction — needs the top-level
+  // connection's `.begin()` (TransactionSql exposes only `.savepoint()`).
+  const db = resolveDbSource(ctx, undefined) as DbConnection | undefined;
+  if (!db) {
+    // Without a DB connection there is no transaction to open. Fall back to
+    // sequential execution — useful for unit tests that don't touch the DB.
+    // Each command runs independently; a failure stops the batch.
+    for (let i = 0; i < commands.length; i++) {
+      const cmd = commands[i];
+      if (!cmd) continue;
+      const res = await executeNestedWrite(
+        ctx,
+        cmd.type,
+        cmd.payload,
+        user,
+        undefined,
+        afterCommitHooks,
+      );
+      results.push(res);
+      if (!res.isSuccess) {
+        // No tx means no rollback — but we still drop afterCommit hooks,
+        // matching the semantic "failure = side-effects don't fire".
+        return finalize({ isSuccess: false, error: res.error, failedIndex: i, results });
+      }
+    }
+    await flushAfterCommit();
+    await flushBatchHooks();
+    return finalize({ isSuccess: true, results });
+  }
+
+  try {
+    await transaction(db, async (tx) => {
+      for (let i = 0; i < commands.length; i++) {
+        const cmd = commands[i];
+        if (!cmd) continue;
+        const res = await executeNestedWrite(
+          ctx,
+          cmd.type,
+          cmd.payload,
+          user,
+          tx,
+          afterCommitHooks,
+        );
+        results.push(res);
+        if (!res.isSuccess) {
+          throw new BatchRollback(i, res.error);
+        }
+      }
+    });
+  } catch (e) {
+    if (e instanceof BatchRollback) {
+      return finalize({
+        isSuccess: false,
+        error: e.failureError,
+        failedIndex: e.failedIndex,
+        results,
+      });
+    }
+    return finalize({
+      isSuccess: false,
+      error: toWriteErrorInfo(wrapToKumiko(e)),
+      failedIndex: results.length,
+      results,
+    });
+  }
+
+  // Commit succeeded — fire deferred side-effects.
+  await flushAfterCommit();
+  await flushBatchHooks();
+  return finalize({ isSuccess: true, results });
+}
+
+// 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).
+export function unwrapSingle(batchResult: BatchResult): WriteResult {
+  if (batchResult.isSuccess) {
+    return (
+      batchResult.results[0] ?? writeFailure(new InternalError({ message: "empty_batch_result" }))
+    );
+  }
+  return (
+    batchResult.results[batchResult.failedIndex] ?? {
+      isSuccess: false,
+      error: batchResult.error,
+    }
+  );
+}

package/src/pipeline/dispatch-query.ts

@@ -0,0 +1,165 @@
+import type { DbRow, DbTx } from "../db/connection";
+import { hasAccess } from "../engine/access";
+import { filterReadFields } from "../engine/field-access";
+import type { SessionUser } from "../engine/types";
+import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors";
+import { assertNoSecretLeak } from "../secrets";
+import type { DispatchContext } from "./dispatch-shared";
+import {
+  buildHandlerContext,
+  enforceRateLimit,
+  ensureFeatureEnabled,
+  runHandlerInstrumented,
+} from "./dispatch-shared";
+
+// Standalone query execution — used by the public dispatcher.query() and
+// by ctx.query/ctx.queryAs inside handlers. Runs the handler, applies
+// field-level read filters for the given user, logs the event.
+export async function executeQuery(
+  ctx: DispatchContext,
+  type: string,
+  payload: unknown,
+  user: SessionUser,
+  tx?: DbTx,
+): Promise<unknown> {
+  return runHandlerInstrumented(ctx, type, "query", user, () =>
+    executeQueryInner(ctx, type, payload, user, tx),
+  );
+}
+
+async function executeQueryInner(
+  ctx: DispatchContext,
+  type: string,
+  payload: unknown,
+  user: SessionUser,
+  tx?: DbTx,
+): Promise<unknown> {
+  const { registry } = ctx;
+  const handler = registry.getQueryHandler(type);
+  if (!handler) throw new NotFoundError("handler", type);
+
+  // Feature-toggle gate runs BEFORE rate-limit on purpose: calls to a
+  // disabled feature must not consume the rate-limit quota — the call
+  // never happened from the feature's perspective. Order is: lookup →
+  // feature-gate → rate-limit → access → validation → handler.
+  await ensureFeatureEnabled(ctx, type, user.tenantId);
+
+  // Rate-limit gate runs BEFORE access-check on purpose: anonymous /
+  // unauthorized callers must hit the cap too (otherwise the limit
+  // would be a free probe-detector for valid credentials). The
+  // resolver throws RateLimitError which the dispatcher's outer
+  // wrapper turns into a 429 response. Inline-skip when the handler
+  // didn't opt in — keeps the hot path zero-cost (no await on a
+  // no-op promise).
+  if (handler.rateLimit !== undefined) {
+    await enforceRateLimit(ctx, handler.rateLimit, type, user);
+  }
+
+  // Default-deny: missing access rule is treated as "no one has access".
+  // The registry boot-validator refuses to register handlers without one,
+  // so in normal boots this branch shouldn't fire — the guard is belt-and-
+  // suspenders in case a handler sneaks through (e.g. runtime injection).
+  if (!hasAccess(user, handler.access)) {
+    throw new AccessDeniedError({
+      message: `access denied for ${type}`,
+      details: { handler: type },
+    });
+  }
+
+  const parsed = handler.schema.safeParse(payload);
+  if (!parsed.success) {
+    throw validationErrorFromZod(parsed.error);
+  }
+
+  // Trash opt-in rides the validated query payload: only the entity-list
+  // schema (and custom query schemas that opt in) carries `includeDeleted`,
+  // so other handlers never see the flag. Visibility filters still apply
+  // downstream (see HandlerContext.includeDeleted) — safe from raw input.
+  const includeDeleted =
+    typeof parsed.data === "object" &&
+    parsed.data !== null &&
+    (parsed.data as Record<string, unknown>)["includeDeleted"] === true; // @cast-boundary validated-payload
+  const handlerContext = buildHandlerContext(ctx, type, user, tx, undefined, includeDeleted);
+  let result = await handler.handler({ type, payload: parsed.data, user }, handlerContext);
+
+  // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data
+  // and can merge custom-fields/computed-counts/tags/etc. Each hook is
+  // responsible for its own field-access on values it adds (the filter
+  // below only knows the entity's stammfields).
+  //
+  // Two firing-pfade kombiniert in dieser Reihenfolge:
+  //   1. Handler-keyed hooks via r.hook("postQuery", "ns:query:list", fn)
+  //      — feuern nur für genau diesen handler
+  //   2. Entity-keyed hooks via r.entityHook("postQuery", "property", fn)
+  //      — feuern für ALLE query-handlers des entity
+  const entityName = registry.getHandlerEntity(type);
+
+  // Handler-keyed postQuery hooks fire for any query (incl. entity-less
+  // standalone queries like "ns:dashboard"). Entity-keyed hooks only apply
+  // when the handler maps to an entity — so this block must NOT be gated on
+  // entityName, or hooks on standalone queries register silently and never fire.
+  const handlerHooks = registry.getPostQueryHooks(type);
+  const entityHooks = entityName ? registry.getEntityPostQueryHooks(entityName) : [];
+  const postQueryHooks = [...handlerHooks, ...entityHooks];
+  if (postQueryHooks.length > 0 && result && typeof result === "object") {
+    if (Array.isArray(result)) {
+      let rows = result as Record<string, unknown>[]; // @cast-boundary engine-payload
+      for (const hook of postQueryHooks) {
+        const out = await hook({ entityName, rows }, handlerContext);
+        rows = [...out.rows];
+      }
+      result = rows;
+    } else if (Array.isArray((result as { rows?: unknown }).rows)) {
+      // @cast-boundary engine-payload
+      const r = result as { rows: Record<string, unknown>[]; nextCursor: string | null };
+      let rows = r.rows;
+      for (const hook of postQueryHooks) {
+        const out = await hook({ entityName, rows }, handlerContext);
+        rows = [...out.rows];
+      }
+      result = { ...r, rows };
+    } else {
+      let rows: Record<string, unknown>[] = [result as Record<string, unknown>]; // @cast-boundary engine-payload
+      for (const hook of postQueryHooks) {
+        const out = await hook({ entityName, rows }, handlerContext);
+        rows = [...out.rows];
+      }
+      // A single-object result carries exactly one row through the hook
+      // pipeline. Returning 0 rows (effect lost) or ≥2 rows (extras
+      // dropped) cannot be represented in the single-object response —
+      // surface it instead of silently falling back / truncating.
+      if (rows.length !== 1) {
+        throw new Error(
+          `postQuery hook on single-object result for "${type}" must return exactly one row, got ${rows.length}`,
+        );
+      }
+      result = rows[0];
+    }
+  }
+
+  // Field-level read filter — only applies to entity-bound results.
+  const entity = entityName ? registry.getEntity(entityName) : undefined;
+  if (entity && result && typeof result === "object") {
+    if (Array.isArray(result)) {
+      result = result.map((row: Record<string, unknown>) => filterReadFields(entity, row, user));
+    } else {
+      const resultAsDbRow = result as DbRow; // @cast-boundary engine-payload
+      if (Array.isArray((resultAsDbRow as { rows?: unknown }).rows)) {
+        // generic handler-result shape narrow
+        const r = result as { rows: Record<string, unknown>[]; nextCursor: string | null }; // @cast-boundary engine-payload
+        result = {
+          ...r,
+          rows: r.rows.map((row) => filterReadFields(entity, row, user)),
+        };
+      } else {
+        result = filterReadFields(entity, result as DbRow, user); // @cast-boundary engine-payload
+      }
+    }
+  }
+
+  // Response-guard: fail the request if a handler accidentally included
+  // a Secret<> branded value in its return. Must run AFTER field-access
+  // filtering so a legitimately stripped secret doesn't false-positive.
+  assertNoSecretLeak(result);
+  return result;
+}