@cosmicdrift/kumiko-framework 0.24.0 → 0.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "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>",

package/src/__tests__/schema-cli-status.integration.test.ts

@@ -65,7 +65,8 @@ describe("runSchemaCli status", () => {
     writeMigration("0001_init.sql", `SELECT 1;`);
     const { out, lines } = captureOut();
     const code = await runSchemaCli(["status"], appDir, out);
-    expect(code).toBe(0);
+    // Exit 1 = pending-drift erkannt (1 Migration lokal, 0 applied); status gated CI non-zero.
+    expect(code).toBe(1);
     const joined = lines.join("\n");
     expect(joined).toContain("0 applied");
     expect(joined).toContain("1 pending");

package/src/bun-db/__tests__/extract-table-info.test.ts

@@ -0,0 +1,51 @@
+// extractTableInfo discriminator-shadow regression.
+//
+// EntityTableMeta carries a `source: "managed" | "unmanaged"` discriminator.
+// table() (dialect) spreads the column handles as enumerable props over the
+// meta object, so an entity field literally named `source` overwrote the
+// discriminator → extractTableInfo failed the meta check, fell into the (dead)
+// drizzle branch, and typed timestamptz columns via getSQLType() as
+// "timestamp with time zone". prepareValue only serializes Temporal.Instant for
+// "timestamptz" → a raw Temporal reached postgres-js → "Cannot use valueOf" on
+// every create of such an entity (e.g. pattern-storage's pattern-file).
+
+import { describe, expect, test } from "bun:test";
+import { buildEntityTable } from "../../db/table-builder";
+import { extractTableInfo } from "../query";
+
+describe("extractTableInfo — EntityTableMeta discriminator is shadow-proof", () => {
+  test("an entity field named `source` does not shadow the discriminator", () => {
+    const table = buildEntityTable("patternFile", {
+      fields: {
+        path: { type: "text", required: true },
+        source: { type: "text", required: true },
+      },
+    });
+    const info = extractTableInfo(table);
+    // The framework-canonical pgType the bun-db serializer matches on — NOT the
+    // drizzle getSQLType() spelling "timestamp with time zone".
+    expect(info.pgTypeOf("inserted_at")).toBe("timestamptz");
+    // The user-defined `source` column is still present + correctly typed.
+    expect(info.pgTypeOf("source")).toBe("text");
+  });
+
+  test.each([
+    "columns",
+    "tableName",
+    "indexes",
+  ])("an entity field named `%s` (another meta key) also does not shadow it", (fieldName) => {
+    const table = buildEntityTable("thing", {
+      fields: { [fieldName]: { type: "text", required: true } },
+    });
+    const info = extractTableInfo(table);
+    expect(info.pgTypeOf("inserted_at")).toBe("timestamptz");
+  });
+
+  test("control entity without a colliding field is unaffected", () => {
+    const table = buildEntityTable("note", {
+      fields: { title: { type: "text", required: true } },
+    });
+    const info = extractTableInfo(table);
+    expect(info.pgTypeOf("inserted_at")).toBe("timestamptz");
+  });
+});

package/src/bun-db/query.ts

@@ -37,32 +37,33 @@ function snakeToCamel(key: string): string {
 import type { BunDbRunner } from "./connection";
 
 // Drizzle-pgTable-Inspection via raw Symbol-access (kein drizzle-orm import).
-// drizzle stores the table name unter `Symbol.for("kumiko:schema:Name")` und die
-// column-map unter `Symbol.for("kumiko:schema:Columns")`.
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
-
-function getTableName(table: unknown): string | null {
-  if (typeof table !== "object" || table === null) return null;
-  const name = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
-  return typeof name === "string" ? name : null;
-}
-
-function extractDrizzleColumns(table: unknown): Map<string, { name: string; sqlType?: string }> {
-  const out = new Map<string, { name: string; sqlType?: string }>();
-  if (typeof table !== "object" || table === null) return out;
-  const cols = (table as Record<symbol, unknown>)[KUMIKO_COLUMNS_SYMBOL];
-  if (typeof cols !== "object" || cols === null) return out;
-  for (const [key, val] of Object.entries(cols as Record<string, unknown>)) {
-    if (typeof val !== "object" || val === null) continue;
-    const colObj = val as { name?: unknown; getSQLType?: () => string };
-    const colName = colObj.name;
-    if (typeof colName !== "string") continue;
-    // Drizzle's getSQLType uses `this` — call as method on colObj.
-    const sqlType = typeof colObj.getSQLType === "function" ? colObj.getSQLType() : undefined;
-    out.set(key, { name: colName, ...(sqlType !== undefined && { sqlType }) });
-  }
-  return out;
+// table() (dialect) stores the canonical, shadow-proof EntityTableMeta under
+// `Symbol.for("kumiko:schema:Meta")`. The column handles on the table object are
+// enumerable props, so an entity field named `source`/`columns`/`tableName`/…
+// would overwrite the matching meta key — reading the meta from the symbol is
+// the only collision-safe path.
+const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
+
+function isEntityTableMeta(v: unknown): v is EntityTableMeta {
+  return (
+    v !== null &&
+    typeof v === "object" &&
+    typeof (v as EntityTableMeta).tableName === "string" &&
+    Array.isArray((v as EntityTableMeta).columns) &&
+    ((v as EntityTableMeta).source === "managed" || (v as EntityTableMeta).source === "unmanaged")
+  );
+}
+
+// Resolve any framework table input to its canonical EntityTableMeta:
+//  - table()/buildEntityTable outputs carry it under KUMIKO_META_SYMBOL, immune
+//    to a column-handle shadowing a meta key.
+//  - buildEntityTableMeta / defineUnmanagedTable return a plain meta with no
+//    handle-spread, so its structural shape is itself unshadowable.
+function asEntityTableMeta(table: unknown): EntityTableMeta | undefined {
+  if (table === null || typeof table !== "object") return undefined;
+  const fromSymbol = (table as Record<symbol, unknown>)[KUMIKO_META_SYMBOL];
+  if (isEntityTableMeta(fromSymbol)) return fromSymbol;
+  return isEntityTableMeta(table) ? table : undefined;
 }
 
 // `db` Input akzeptiert drei Shapes:
@@ -218,69 +219,30 @@ export type TableInfo = {
 };
 
 export function extractTableInfo(table: TableLike): TableInfo {
-  // EntityTableMeta discriminator: hat source-property "managed" | "unmanaged"
-  if (
-    table !== null &&
-    typeof table === "object" &&
-    "source" in table &&
-    (table.source === "managed" || table.source === "unmanaged")
-  ) {
-    const meta = table as EntityTableMeta;
-    const colByField = new Map<string, string>();
-    const fieldByCol = new Map<string, string>();
-    const typeByCol = new Map<string, string>();
-    const bigintModeByCol = new Map<string, "number" | "bigint">();
-    for (const c of meta.columns) {
-      typeByCol.set(c.name, c.pgType);
-      if (c.bigintJsMode !== undefined) bigintModeByCol.set(c.name, c.bigintJsMode);
-      // EntityTableMeta column names are snake_case. Map snake → snake AND
-      // derive a camelCase JS field-name so result rows can be renamed back
-      // to the API shape (`aggregate_id` → `aggregateId`).
-      colByField.set(c.name, c.name);
-      const camel = snakeToCamel(c.name);
-      if (camel !== c.name) colByField.set(camel, c.name);
-      fieldByCol.set(c.name, camel === c.name ? c.name : camel);
-    }
-    return {
-      name: meta.tableName,
-      columnOf: (field) => colByField.get(field) ?? toSnakeCase(field),
-      pgTypeOf: (col) => typeByCol.get(col),
-      bigintJsModeOf: (col) => bigintModeByCol.get(col),
-      fieldOf: (col) => fieldByCol.get(col) ?? snakeToCamel(col),
-      hasColumn: (fieldOrColumn) => colByField.has(fieldOrColumn) || fieldByCol.has(fieldOrColumn),
-    };
-  }
-  // drizzle pgTable: tableName via Symbol.for("kumiko:schema:Name"), columns via
-  // enumerable properties (jeder col-object hat .name + .getSQLType()).
-  // Wir lesen Beide via raw Symbol/Property-access — kein drizzle-orm import.
-  const name = getTableName(table);
-  if (!name) {
+  const meta = asEntityTableMeta(table);
+  if (!meta) {
     throw new Error(
-      "bun-db.extractTableInfo: table-Argument ist weder EntityTableMeta noch drizzle pgTable",
+      "bun-db.extractTableInfo: table is not a kumiko EntityTableMeta — " +
+        "build it via buildEntityTable / buildEntityTableMeta / table().",
     );
   }
-  const cols = extractDrizzleColumns(table);
   const colByField = new Map<string, string>();
   const fieldByCol = new Map<string, string>();
   const typeByCol = new Map<string, string>();
   const bigintModeByCol = new Map<string, "number" | "bigint">();
-  if (
-    table !== null &&
-    typeof table === "object" &&
-    "columns" in table &&
-    Array.isArray((table as EntityTableMeta).columns)
-  ) {
-    for (const c of (table as EntityTableMeta).columns) {
-      if (c.bigintJsMode !== undefined) bigintModeByCol.set(c.name, c.bigintJsMode);
-    }
-  }
-  for (const [field, { name: colName, sqlType }] of cols) {
-    colByField.set(field, colName);
-    fieldByCol.set(colName, field);
-    if (sqlType) typeByCol.set(colName, sqlType);
+  for (const c of meta.columns) {
+    typeByCol.set(c.name, c.pgType);
+    if (c.bigintJsMode !== undefined) bigintModeByCol.set(c.name, c.bigintJsMode);
+    // EntityTableMeta column names are snake_case. Map snake → snake AND
+    // derive a camelCase JS field-name so result rows can be renamed back
+    // to the API shape (`aggregate_id` → `aggregateId`).
+    colByField.set(c.name, c.name);
+    const camel = snakeToCamel(c.name);
+    if (camel !== c.name) colByField.set(camel, c.name);
+    fieldByCol.set(c.name, camel === c.name ? c.name : camel);
   }
   return {
-    name,
+    name: meta.tableName,
     columnOf: (field) => colByField.get(field) ?? toSnakeCase(field),
     pgTypeOf: (col) => typeByCol.get(col),
     bigintJsModeOf: (col) => bigintModeByCol.get(col),
@@ -731,16 +693,6 @@ function insertEntries(info: TableInfo, values: Record<string, unknown>): Insert
     });
 }
 
-function isEntityTableMeta(table: unknown): table is EntityTableMeta {
-  return (
-    typeof table === "object" &&
-    table !== null &&
-    "source" in table &&
-    (table.source === "managed" || table.source === "unmanaged") &&
-    "columns" in table
-  );
-}
-
 function resolveConflictColumns(
   table: TableLike,
   info: TableInfo,
@@ -749,8 +701,11 @@ function resolveConflictColumns(
   if (conflictKeys !== undefined && conflictKeys.length > 0) {
     return conflictKeys.map((field) => info.columnOf(field));
   }
-  if (isEntityTableMeta(table)) {
-    const pks = table.columns.filter((c) => c.primaryKey).map((c) => c.name);
+  // Read the shadow-proof meta — `table.columns` directly would be the handle
+  // object when an entity has a field named `columns`.
+  const meta = asEntityTableMeta(table);
+  if (meta) {
+    const pks = meta.columns.filter((c) => c.primaryKey).map((c) => c.name);
     if (pks.length > 0) return pks;
   }
   if (info.hasColumn("id")) return [info.columnOf("id")];

package/src/db/dialect.ts

@@ -40,6 +40,11 @@ export type ColumnHandle = {
 
 const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
 const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
+// Shadow-proof handle on the EntityTableMeta. The column handles below are
+// spread as enumerable props, so an entity field named `source`/`columns`/
+// `tableName`/… would overwrite the matching meta key. extractTableInfo reads
+// the canonical meta from this symbol instead of the (shadowable) props.
+const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
 
 // SchemaTable — opaque shape with both EntityTableMeta + Symbol-based
 // introspection. Returned by `table(...)`.
@@ -469,6 +474,7 @@ export function table<TCols extends ColumnMap>(
   const out = Object.assign({}, base, handles, {
     [KUMIKO_NAME_SYMBOL]: tableName,
     [KUMIKO_COLUMNS_SYMBOL]: handles,
+    [KUMIKO_META_SYMBOL]: base,
   }) as SchemaTable;
   return out;
 }

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

@@ -81,6 +81,22 @@ export async function selectAggregateMaxVersion(db: AnyDb, aggregateId: string):
   return rows[0]?.v ?? 0;
 }
 
+/** tenant_id the aggregate's events were written under — no membership/tenant
+ *  filter. A r.systemScope() aggregate (e.g. user) lives in whichever tenant
+ *  its creating executor used, which need not be a tenant the subject holds a
+ *  membership in. Returns null for unknown streams. */
+export async function selectAggregateStreamTenant(
+  db: AnyDb,
+  aggregateId: string,
+  aggregateType: string,
+): Promise<string | null> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT "tenant_id" AS t FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = $2 ORDER BY "version" LIMIT 1`,
+    [aggregateId, aggregateType],
+  )) as ReadonlyArray<{ t: string | null }>;
+  return rows[0]?.t ?? null;
+}
+
 export async function selectEventsHighWaterMark(db: AnyDb): Promise<bigint> {
   const rows = (await asRawClient(db).unsafe(
     `SELECT COALESCE(MAX("id"), 0)::bigint AS max FROM "kumiko_events"`,

package/src/engine/__tests__/projection-helpers.test.ts

@@ -3,15 +3,20 @@ import type { StoredEvent } from "../../event-store/event-store";
 import { setFields } from "../projection-helpers";
 import type { ProjectionTable } from "../types/projection";
 
-// Minimal fake table: only the `id` column is needed for setFields, plus
-// the kumiko:schema:Name + kumiko:schema:Columns symbols that bun-db introspects for
-// table-name + column-mapping. We don't run real SQL — unsafe() is mocked.
-const fakeIdCol = { name: "id" };
+// Minimal fake table: an EntityTableMeta (what bun-db introspects for
+// table-name + column-mapping) plus a top-level `id` handle, which setFields
+// existence-checks before building its apply fn. We don't run real SQL —
+// unsafe() is mocked.
 const fakeTable = Object.assign(
-  { id: fakeIdCol },
+  { id: { name: "id" } },
   {
-    [Symbol.for("kumiko:schema:Name")]: "fake_table",
-    [Symbol.for("kumiko:schema:Columns")]: { id: fakeIdCol },
+    tableName: "fake_table",
+    source: "unmanaged",
+    indexes: [],
+    columns: [
+      { name: "id", pgType: "uuid", notNull: true },
+      { name: "status", pgType: "text", notNull: false },
+    ],
   },
 ) as unknown as ProjectionTable;
 

package/src/engine/registry.ts

@@ -422,18 +422,18 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     // Lifecycle hooks: keyed by handler QN. featureName rides along on each
     // hook entry — defineFeature sets it, the registry just appends.
     // Save/delete hooks target write handlers, query hooks target query handlers.
-    mergeHookListQualified(preSaveHooks, feature.hooks.preSave, feature.name, "write");
-    mergeHookListQualified(postSaveHooks, feature.hooks.postSave, feature.name, "write");
-    mergeHookListQualified(preDeleteHooks, feature.hooks.preDelete, feature.name, "write");
-    mergeHookListQualified(postDeleteHooks, feature.hooks.postDelete, feature.name, "write");
-    mergeHookListQualified(preQueryHooks, feature.hooks.preQuery, feature.name, "query");
-    mergeHookListQualified(postQueryHooks, feature.hooks.postQuery, feature.name, "query");
+    mergeHookListQualified(preSaveHooks, feature.hooks?.preSave, feature.name, "write");
+    mergeHookListQualified(postSaveHooks, feature.hooks?.postSave, feature.name, "write");
+    mergeHookListQualified(preDeleteHooks, feature.hooks?.preDelete, feature.name, "write");
+    mergeHookListQualified(postDeleteHooks, feature.hooks?.postDelete, feature.name, "write");
+    mergeHookListQualified(preQueryHooks, feature.hooks?.preQuery, feature.name, "query");
+    mergeHookListQualified(postQueryHooks, feature.hooks?.postQuery, feature.name, "query");
 
     // Entity hooks: NOT prefixed, keyed by entity name
-    mergeHookList(entityPostSaveHooks, feature.entityHooks.postSave);
-    mergeHookList(entityPreDeleteHooks, feature.entityHooks.preDelete);
-    mergeHookList(entityPostDeleteHooks, feature.entityHooks.postDelete);
-    mergeHookList(entityPostQueryHooks, feature.entityHooks.postQuery);
+    mergeHookList(entityPostSaveHooks, feature.entityHooks?.postSave);
+    mergeHookList(entityPreDeleteHooks, feature.entityHooks?.preDelete);
+    mergeHookList(entityPostDeleteHooks, feature.entityHooks?.postDelete);
+    mergeHookList(entityPostQueryHooks, feature.entityHooks?.postQuery);
 
     // F3 search-payload-extensions: per-entity contributors merged additively
     for (const [entityName, contributors] of Object.entries(
@@ -453,9 +453,9 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
       }
       extensionMap.set(extName, extDef);
     }
-    extensionUsages.push(...feature.extensionUsages);
-    allReferenceData.push(...feature.referenceData);
-    allConfigSeeds.push(...feature.configSeeds);
+    extensionUsages.push(...(feature.extensionUsages ?? []));
+    allReferenceData.push(...(feature.referenceData ?? []));
+    allConfigSeeds.push(...(feature.configSeeds ?? []));
 
     // Metrics: validate + qualify per feature. Collisions across features are
     // rejected here — two features can't both register "created_total" under
@@ -477,7 +477,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     // Secret keys: already qualified during defineFeature (same "<feature>:<short>"
     // convention used elsewhere). Reject cross-feature duplicates — extensions
     // could theoretically register on another feature's namespace.
-    for (const def of Object.values(feature.secretKeys)) {
+    for (const def of Object.values(feature.secretKeys ?? {})) {
       if (secretKeyMap.has(def.qualifiedName)) {
         throw new Error(
           `[Kumiko Secrets] Secret key "${def.qualifiedName}" registered multiple times. ` +
@@ -567,7 +567,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     // correctness — the only way to hit this is a hand-built FeatureDefinition
     // bypassing defineFeature's per-feature duplicate check.
     const declaredShortNames = new Set<string>();
-    for (const def of Object.values(feature.claimKeys)) {
+    for (const def of Object.values(feature.claimKeys ?? {})) {
       if (claimKeyMap.has(def.qualifiedName)) {
         throw new Error(
           `[Kumiko ClaimKeys] Claim key "${def.qualifiedName}" registered multiple times. ` +
@@ -670,7 +670,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     // on undeclared inner-keys (typo / rename drift). Features that don't
     // declare claimKeys skip the check entirely — it's opt-in.
     const declaredKeys = declaredShortNames.size > 0 ? declaredShortNames : undefined;
-    for (const fn of feature.authClaimsHooks) {
+    for (const fn of feature.authClaimsHooks ?? []) {
       authClaimsHooks.push({
         featureName: feature.name,
         fn,
@@ -1035,7 +1035,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
 
   // Validate: all required features must be registered
   for (const feature of features) {
-    for (const required of feature.requires) {
+    for (const required of feature.requires ?? []) {
       if (!featureMap.has(required)) {
         throw new Error(
           `Feature "${feature.name}" requires feature "${required}" which is not registered`,

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/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

@@ -803,7 +803,17 @@ export function createDispatcher(
             const out = await hook({ entityName, rows }, handlerContext);
             rows = [...out.rows];
           }
-          result = rows[0] ?? result;
+          // 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.
+          const [only, ...extra] = rows;
+          if (only === undefined || extra.length > 0) {
+            throw new Error(
+              `postQuery hook on single-object result for "${type}" must return exactly one row, got ${rows.length}`,
+            );
+          }
+          result = only;
         }
       }
 

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) &&
+    "indexes" in v &&
+    "source" in v
+  );
+}
+
 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/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 {