@cosmicdrift/kumiko-framework 0.24.0 → 0.25.0

package/src/errors/classes.ts

@@ -83,8 +83,10 @@ export class NotFoundError extends KumikoError {
     const idStr = id !== undefined ? String(id) : undefined;
     // The reason string follows `<snake_entity>_not_found` — keeps a stable,
     // client-friendly tag that survives wire serialization even if the entity
-    // name is later renamed for display purposes.
-    const reason = `${toSnakeCase(entity)}_not_found`;
+    // name is later renamed for display purposes. Strip the leading underscore
+    // toSnakeCase emits for a PascalCase name ("Invoice" → "_invoice") so the
+    // wire tag stays "invoice_not_found", not "_invoice_not_found".
+    const reason = `${toSnakeCase(entity).replace(/^_/, "")}_not_found`;
     const details: NotFoundDetails & { reason: string } = { reason, entity, id: idStr };
     super({
       message: idStr !== undefined ? `${entity} ${idStr} not found` : `${entity} not found`,

package/src/event-store/event-store.ts

@@ -4,6 +4,7 @@ import {
   insertSubsequentEventRow,
   notifyPgChannel,
   selectAggregateMaxVersion,
+  selectAggregateStreamTenant,
   selectEventsHighWaterMark,
   selectStreamMaxVersion,
 } from "../db/queries/event-store";
@@ -282,6 +283,20 @@ export async function getAggregateStreamMaxVersion(
   return selectAggregateMaxVersion(db, aggregateId);
 }
 
+/** Stream tenant of an aggregate (the tenant_id its events live under), with no
+ *  membership/tenant filter. Recovers the write target for a systemScope
+ *  aggregate whose stream tenant isn't one of the subject's memberships.
+ *  Returns null for unknown streams. */
+export async function getAggregateStreamTenant(
+  db: DbRunner,
+  aggregateId: string,
+  aggregateType: string,
+): Promise<TenantId | null> {
+  const tenantId = await selectAggregateStreamTenant(db, aggregateId, aggregateType);
+  // DB-boundary: kumiko_events.tenant_id is a TenantId-shaped uuid column.
+  return tenantId as TenantId | null;
+}
+
 // Global high-water-mark = MAX(events.id). Marten/Wolverine standard for
 // projection/consumer lag math: lag = HWM - cursor. Single-row aggregate over
 // the bigserial PK index — sub-millisecond cost. Returns 0n on an empty log

package/src/event-store/index.ts

@@ -13,6 +13,7 @@ export {
   type EventMetadata,
   type EventToAppend,
   getAggregateStreamMaxVersion,
+  getAggregateStreamTenant,
   getEventsHighWaterMark,
   getStreamVersion,
   loadAggregate,

package/src/files/__tests__/file-ref-entity.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import type { ColumnMeta } from "../../db/entity-table-meta";
+import { fileRefsTable } from "../file-ref-table";
+
+// `fileRefsTable` is the live buildEntityTable() output the app boots with.
+// Its runtime shape is a SchemaTable (EntityTableMeta & drizzle table), so the
+// EntityTableMeta `columns` carry the resolved NOT NULL / DEFAULT per column —
+// the drizzle-facing static type (EntityTable<E>) hides them, hence the cast.
+// Importing fileRefEntity directly here would hit the engine↔file-ref-table
+// init cycle (biome sorts it before file-ref-table); going through the built
+// table sidesteps it and tests the exact object production uses.
+const columns = (fileRefsTable as unknown as { readonly columns: readonly ColumnMeta[] }).columns;
+const col = (name: string): readonly ColumnMeta[] => columns.filter((c) => c.name === name);
+
+describe("fileRefEntity base-column drift", () => {
+  // Regression: an earlier revision declared `insertedAt`/`insertedById` as
+  // entity fields. The field-column then OVERRODE the framework base column in
+  // the {...base, ...field} last-wins merge (entity-table-meta.ts), dropping
+  // its NOT NULL DEFAULT now() and making inserted_at silently nullable — a
+  // production INSERT could then leave it null. Re-adding either field shadows
+  // the base column again and turns these red.
+  test("inserted_at stays NOT NULL DEFAULT now() (base column, not field-shadowed)", () => {
+    const insertedAt = col("inserted_at");
+    expect(insertedAt).toHaveLength(1); // exactly one — not duplicated by a redeclared field
+    expect(insertedAt[0]?.notNull).toBe(true);
+    expect(insertedAt[0]?.defaultSql).toBe("now()");
+  });
+
+  test("inserted_by_id stays framework-managed nullable (not redeclared as a required field)", () => {
+    const insertedById = col("inserted_by_id");
+    expect(insertedById).toHaveLength(1);
+    expect(insertedById[0]?.notNull).toBe(false);
+  });
+});

package/src/pipeline/__tests__/dispatcher.test.ts

@@ -159,6 +159,59 @@ describe("dispatcher.query", () => {
   });
 });
 
+// --- postQuery hooks on standalone (entity-less) queries ---
+
+describe("dispatcher.query postQuery hooks", () => {
+  test("handler-keyed postQuery hook fires on a standalone (no-colon) query", async () => {
+    // Standalone queries (name without colon, e.g. "dashboard") map to no
+    // entity. Handler-keyed postQuery hooks must still fire — gating the hook
+    // pass on entity-existence makes such a hook register silently + never run.
+    const feature = defineFeature("dash", (r) => {
+      r.queryHandler("dashboard", z.object({}), async () => ({ count: 1 }), {
+        access: { openToAll: true },
+      });
+      r.hook("postQuery", "dashboard", async ({ entityName, rows }) => {
+        expect(entityName).toBeUndefined();
+        return { rows: rows.map((row) => ({ ...row, enriched: true })) };
+      });
+    });
+
+    const dispatcher = createDispatcher(createRegistry([feature]), {});
+    const result = await dispatcher.query("dash:query:dashboard", {}, createTestUser());
+    expect(result).toEqual({ count: 1, enriched: true });
+  });
+
+  test("postQuery hook does not run for a result with rows:null (not an array)", async () => {
+    // `{ rows: null }` is a legitimate 'nothing found' shape — it must take the
+    // single-object branch, not the rows-list branch (which would crash on
+    // [...null]). The hook here returns the row unchanged so the shape survives.
+    const feature = defineFeature("nullrows", (r) => {
+      r.queryHandler("dashboard", z.object({}), async () => ({ rows: null, nextCursor: null }), {
+        access: { openToAll: true },
+      });
+      r.hook("postQuery", "dashboard", async ({ rows }) => ({ rows }));
+    });
+
+    const dispatcher = createDispatcher(createRegistry([feature]), {});
+    const result = await dispatcher.query("nullrows:query:dashboard", {}, createTestUser());
+    expect(result).toEqual({ rows: null, nextCursor: null });
+  });
+
+  test("single-object postQuery hook returning ≠1 row throws", async () => {
+    const feature = defineFeature("multi", (r) => {
+      r.queryHandler("dashboard", z.object({}), async () => ({ count: 1 }), {
+        access: { openToAll: true },
+      });
+      r.hook("postQuery", "dashboard", async ({ rows }) => ({ rows: [...rows, ...rows] }));
+    });
+
+    const dispatcher = createDispatcher(createRegistry([feature]), {});
+    await expect(dispatcher.query("multi:query:dashboard", {}, createTestUser())).rejects.toThrow(
+      /must return exactly one row, got 2/,
+    );
+  });
+});
+
 // --- Dispatch: Command (fire-and-forget) ---
 
 describe("dispatcher.command", () => {

package/src/pipeline/__tests__/post-query-hook.integration.test.ts

@@ -68,13 +68,50 @@ const postQueryFeature = defineFeature("postquerytest", (r) => {
   r.entityHook("postQuery", widget, entityKeyedHook);
 });
 
+// --- Single-object-result invariant fixtures ---
+//
+// A query handler that returns a plain object (not array, not {rows}) carries
+// exactly one row through the hook pipeline. A hook that returns 0 or ≥2 rows
+// for such a result used to be swallowed (`rows[0] ?? result`): 0 rows fell
+// back to the unhooked original, ≥2 silently dropped the extras. Both now
+// surface as a dispatcher error instead.
+
+const gadgetEntity = createEntity({
+  table: "read_post_query_gadgets",
+  fields: { name: createTextField({ required: true }) },
+});
+const gizmoEntity = createEntity({
+  table: "read_post_query_gizmos",
+  fields: { name: createTextField({ required: true }) },
+});
+
+const dropRowHook: PostQueryHookFn = async () => ({ rows: [] });
+const duplicateRowHook: PostQueryHookFn = async ({ rows }) => ({ rows: [...rows, ...rows] });
+
+const singleObjectFeature = defineFeature("singleobjtest", (r) => {
+  const gadget = r.entity("gadget", gadgetEntity);
+  r.queryHandler("gadget:get", z.object({}), async () => ({ id: "g1", name: "Gadget" }), {
+    access: { openToAll: true },
+  });
+  r.entityHook("postQuery", gadget, dropRowHook);
+
+  const gizmo = r.entity("gizmo", gizmoEntity);
+  r.queryHandler("gizmo:get", z.object({}), async () => ({ id: "z1", name: "Gizmo" }), {
+    access: { openToAll: true },
+  });
+  r.entityHook("postQuery", gizmo, duplicateRowHook);
+});
+
 // --- Test stack ---
 
 let stack: TestStack;
 const admin = TestUsers.admin;
 
 beforeAll(async () => {
-  stack = await setupTestStack({ features: [postQueryFeature], systemHooks: [] });
+  stack = await setupTestStack({
+    features: [postQueryFeature, singleObjectFeature],
+    systemHooks: [],
+  });
 });
 
 afterAll(async () => {
@@ -114,3 +151,15 @@ describe("postQuery-Hook integration through dispatcher", () => {
     expect(result.nextCursor).toBeNull();
   });
 });
+
+describe("single-object-result postQuery invariant: exactly one row", () => {
+  test("hook returning 0 rows surfaces as 500 (not a silent fallback to the unhooked result)", async () => {
+    const res = await stack.http.query("singleobjtest:query:gadget:get", {}, admin);
+    expect(res.status).toBe(500);
+  });
+
+  test("hook returning ≥2 rows surfaces as 500 (not a silent truncation to the first)", async () => {
+    const res = await stack.http.query("singleobjtest:query:gizmo:get", {}, admin);
+    expect(res.status).toBe(500);
+  });
+});

package/src/pipeline/dispatcher.ts

@@ -686,7 +686,7 @@ export function createDispatcher(
     if (!rateLimit) return;
     if (!context.rateLimit) {
       throw new InternalError({
-        message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rateLimiting feature or remove the option.`,
+        message: `Handler "${handlerName}" declares rateLimit but no RateLimitResolver is configured. Load the rate-limiting feature or remove the option.`,
       });
     }
     const reqCtx = requestContext.get();
@@ -776,56 +776,66 @@ export function createDispatcher(
     //   2. Entity-keyed hooks via r.entityHook("postQuery", "property", fn)
     //      — feuern für ALLE query-handlers des entity
     const entityName = registry.getHandlerEntity(type);
-    if (entityName) {
-      const handlerHooks = registry.getPostQueryHooks(type);
-      const entityHooks = 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 ("rows" in result) {
-          // @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];
-          }
-          result = rows[0] ?? result;
+
+    // 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
-      const entity = registry.getEntity(entityName);
-      if (entity && result && typeof result === "object") {
-        if (Array.isArray(result)) {
-          result = result.map((row: Record<string, unknown>) =>
-            filterReadFields(entity, row, user),
-          );
+    // 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 {
-          const resultAsDbRow = result as DbRow; // @cast-boundary engine-payload
-          if ("rows" in resultAsDbRow) {
-            // 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
-          }
+          result = filterReadFields(entity, result as DbRow, user); // @cast-boundary engine-payload
         }
       }
     }

package/src/pipeline/system-hooks.ts

@@ -98,7 +98,7 @@ function reconstructStateForSearch(
 // Build a SearchDocument from raw field-state. Parallel to the old
 // buildSearchDocument that took a SaveContext — same selector logic, just
 // a different input shape.
-async function buildSearchDocument(
+export async function buildSearchDocument(
   entityName: string,
   entityId: EntityId,
   state: Record<string, unknown>,
@@ -143,12 +143,24 @@ async function buildSearchDocument(
   // F3 — Search-Payload-Extensions: contributors merge flat fields into the
   // search-doc (customFields-bundle / tags / computed-counts / etc.).
   // Sequential await — extensions are expected sync or sub-millisecond async;
-  // sequential keeps the path simple and deterministic. If parallel ever
-  // matters, switch to Promise.all but bind contributor-output-precedence
-  // (last-wins vs. merge-conflict) explicitly.
+  // sequential keeps the path simple and deterministic.
+  //
+  // Precedence is base-fields-win: a contributor key that collides with a
+  // searchable Stammfield is dropped (not silently merged over the real value)
+  // and warned. A jsonb custom-field that happens to share a Stammfield name
+  // must not shadow the indexed Stammfield.
   for (const contribute of extensions) {
     const contributed = await contribute({ entityName, entityId, state });
-    Object.assign(fields, contributed);
+    for (const [key, value] of Object.entries(contributed)) {
+      if (Object.hasOwn(fields, key)) {
+        console.warn(
+          `[kumiko:search] searchPayloadExtension on "${entityName}" tried to overwrite ` +
+            `Stammfield "${key}" — keeping the base field. Rename the contributor key.`,
+        );
+        continue;
+      }
+      fields[key] = value;
+    }
   }
 
   return {

package/src/stack/table-helpers.ts

@@ -13,6 +13,7 @@ import { buildEntityTable, toTableName } from "../db/table-builder";
 import type { EventDispatcher } from "../pipeline";
 
 const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
+const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
 function tableNameOf(table: unknown): string {
   if (typeof table !== "object" || table === null) {
     throw new Error("table-helpers: table is not a SchemaTable object");
@@ -53,17 +54,26 @@ export async function unsafeEnsureEntityTable(
 // Tables produced by the native dialect already carry EntityTableMeta-shape
 // (source/columns/indexes). renderTableDdl converts that to CREATE TABLE +
 // CREATE INDEX statements executed via db/queries/test-stack.
+function isMetaShape(v: unknown): v is EntityTableMeta {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    typeof (v as EntityTableMeta).tableName === "string" &&
+    Array.isArray((v as EntityTableMeta).columns) &&
+    Array.isArray((v as EntityTableMeta).indexes) &&
+    ((v as EntityTableMeta).source === "managed" || (v as EntityTableMeta).source === "unmanaged")
+  );
+}
+
 function tableToMeta(table: unknown): EntityTableMeta {
-  if (
-    typeof table === "object" &&
-    table !== null &&
-    "tableName" in table &&
-    "columns" in table &&
-    "indexes" in table &&
-    "source" in table
-  ) {
-    return table as EntityTableMeta;
+  // table() spreads column handles as enumerable props, so a field named
+  // `columns`/`tableName`/`source`/… shadows the matching meta key — read the
+  // canonical meta from the unshadowable symbol when present.
+  if (table !== null && typeof table === "object") {
+    const fromSymbol = (table as Record<symbol, unknown>)[KUMIKO_META_SYMBOL];
+    if (isMetaShape(fromSymbol)) return fromSymbol;
   }
+  if (isMetaShape(table)) return table;
   throw new Error("unsafePushTables: argument is not a SchemaTable / EntityTableMeta");
 }
 

package/src/stack/test-stack.ts

@@ -171,8 +171,8 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   // everything registered via r.projection() — keeps tests from having to
   // know which projections a feature happens to declare. Two projections
   // backed by the same physical table (e.g. an alternative apply-shape for
-  // the same read-model in a test feature) are deduped by Drizzle-table
-  // reference so drizzle-kit doesn't emit duplicate CREATE TABLE statements.
+  // the same read-model in a test feature) are deduped by table reference so
+  // we emit only one CREATE TABLE per physical table.
   const projectionTables: Record<string, unknown> = {};
   const seenTables = new Set<unknown>();
   for (const feature of options.features) {
@@ -205,8 +205,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     // unsafePushTables emits raw CREATE TABLE — fine for ephemeral test DBs but
     // collides on re-boot against a persistent DB whose projection tables
     // were created during a previous run. Filter out the ones that already
-    // exist; drizzle-kit's diff machinery would otherwise emit CREATE for
-    // them again.
+    // exist so the re-boot doesn't fail on duplicate CREATE TABLE.
     const { tableExists } = await import("../db/schema-inspection");
     const missing: Record<string, unknown> = {};
     for (const [key, tbl] of Object.entries(projectionTables)) {

package/src/testing/db-cleanup.ts

@@ -3,19 +3,17 @@
  * beforeEach hooks. All table clears go through typed `deleteMany` (empty
  * where = full table wipe). Raw SQL stays out of test files.
  */
+import type { EntityTableMeta } from "../db/entity-table-meta";
 import { type AnyDb, deleteMany } from "../db/query";
 
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
-
-/** EntityTableMeta, drizzle pgTable, or plain table name string. */
+/** EntityTableMeta, a built table, or a plain table name string. */
 export type ClearableTable = string | { readonly tableName?: string } | unknown;
 
-function tableFromName(name: string): unknown {
-  return {
-    [KUMIKO_NAME_SYMBOL]: name,
-    [KUMIKO_COLUMNS_SYMBOL]: {},
-  };
+// A full-table wipe (empty where) only needs the table name — give deleteMany
+// a minimal-but-canonical EntityTableMeta so extractTableInfo accepts it
+// without inferring columns.
+function tableFromName(name: string): EntityTableMeta {
+  return { tableName: name, columns: [], indexes: [], source: "unmanaged" };
 }
 
 function resolveClearableTable(table: ClearableTable): unknown {

package/src/errors/__tests__/field-issue-compat.test.ts

@@ -1,16 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import type { FieldIssue as FrameworkFieldIssue } from "@cosmicdrift/kumiko-framework/errors";
-import type { FieldIssue as HeadlessFieldIssue } from "@cosmicdrift/kumiko-headless";
-
-describe("FieldIssue cross-package contract", () => {
-  test("framework and headless FieldIssue shapes are assignable", () => {
-    const frameworkIssue: FrameworkFieldIssue = {
-      path: "title",
-      code: "too_small",
-      i18nKey: "errors.validation.too_small",
-      params: { minimum: 1 },
-    };
-    const headlessIssue: HeadlessFieldIssue = frameworkIssue;
-    expect(headlessIssue.path).toBe("title");
-  });
-});