@cosmicdrift/kumiko-framework 0.109.0 → 0.110.0

package/package.json

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

package/src/api/__tests__/batch.integration.test.ts

@@ -1,6 +1,7 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
+import type { TableColumns } from "../../db/dialect";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { asRawClient, selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";
@@ -36,7 +37,9 @@ const auditEntity = createEntity({
     itemId: createTextField({ required: true }),
   },
 });
-const auditTable = buildEntityTable("audit", auditEntity);
+// Brand (#742) is compile-time-only; the postSave hook writes this sink via method-form,
+// so hold it at the unbranded TableColumns view (identical runtime shape).
+const auditTable: TableColumns = buildEntityTable("audit", auditEntity);
 
 // Hook invocation logs — reset per test. Captures which phase each hook saw.
 const inTxHookLog: Array<{ id: EntityId; name: string }> = [];

package/src/bun-db/__tests__/write-brand.test.ts

@@ -8,6 +8,7 @@
 import { expect, test } from "bun:test";
 import { defineUnmanagedTable } from "../../db/entity-table-meta";
 import { buildEntityTable } from "../../db/table-builder";
+import type { TenantDb } from "../../db/tenant-db";
 import { createEntity, createTextField } from "../../engine";
 import { type AnyDb, deleteMany, insertOne, selectMany, updateMany } from "../query";
 
@@ -41,8 +42,28 @@ async function _readAllowsManagedEntity(db: AnyDb): Promise<void> {
   await selectMany(db, brandedEntity, { id: "1" });
 }
 
+// Method-form (ctx.db.insertOne/updateMany/deleteMany) rejects the brand too — a
+// projection written past its event stream is wiped on rebuild whether the write
+// went through the free function or the TenantDb method.
+async function _methodFormRejectsManagedEntity(db: TenantDb): Promise<void> {
+  // @ts-expect-error — managed EntityTable is executor-only; method-form insert is a compile error.
+  await db.insertOne(brandedEntity, { title: "x" });
+  // @ts-expect-error — method-form update on a managed EntityTable is rejected.
+  await db.updateMany(brandedEntity, { title: "y" }, { id: "1" });
+  // @ts-expect-error — method-form delete on a managed EntityTable is rejected.
+  await db.deleteMany(brandedEntity, { id: "1" });
+}
+
+async function _methodFormReadAllowsManagedEntity(db: TenantDb): Promise<void> {
+  // Method-form reads on a managed EntityTable stay fine (reads keep the plain param).
+  await db.selectMany(brandedEntity, { id: "1" });
+  await db.fetchOne(brandedEntity, { id: "1" });
+}
+
 test("ES-write brand: compile-time contracts are wired", () => {
   expect(_writeRejectsManagedEntity).toBeDefined();
   expect(_writeAllowsUnmanagedTable).toBeDefined();
   expect(_readAllowsManagedEntity).toBeDefined();
+  expect(_methodFormRejectsManagedEntity).toBeDefined();
+  expect(_methodFormReadAllowsManagedEntity).toBeDefined();
 });

package/src/db/__tests__/tenant-db-where-merge.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { createEntity, createTextField } from "../../engine";
 import { testTenantId } from "../../stack";
+import type { TableColumns } from "../dialect";
 import { buildEntityTable } from "../table-builder";
 import { createTenantDb } from "../tenant-db";
 
@@ -13,7 +14,9 @@ const entity = createEntity({
   table: "merge_items",
   fields: { name: createTextField({ required: true }) },
 });
-const table = buildEntityTable("mergeItem", entity);
+// Brand (#742) is compile-time-only; hold the handle at the unbranded TableColumns
+// view so the method-form scoping test still compiles (runtime shape is identical).
+const table: TableColumns = buildEntityTable("mergeItem", entity);
 
 const own = testTenantId(1);
 const foreign = testTenantId(2);

package/src/db/__tests__/tenant-db.integration.test.ts

@@ -10,7 +10,7 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "../../stack";
-import { table as pgTable, serial, text, timestamp } from "../dialect";
+import { table as pgTable, serial, type TableColumns, text, timestamp } from "../dialect";
 import { buildEntityTable } from "../table-builder";
 import { createTenantDb } from "../tenant-db";
 
@@ -26,7 +26,11 @@ const entity = createEntity({
   softDelete: true,
 });
 
-const table = buildEntityTable("tenantDbItem", entity);
+// The ES-write brand (#742) is a compile-time phantom — no runtime property. This
+// suite exercises TenantDb method-form scoping on a real entity table, so the handle
+// is held at the unbranded TableColumns view: identical runtime shape, and both reads
+// and method-form writes accept it (a branded EntityTable is now rejected).
+const table: TableColumns = buildEntityTable("tenantDbItem", entity);
 
 // --- System table (no tenantId — like job_runs) ---
 

package/src/db/tenant-db.ts

@@ -12,10 +12,21 @@ import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
 import type { DbRunner } from "./connection";
 import type { TableColumns } from "./dialect";
+import type { EntityTableMeta } from "./entity-table-meta";
+import type { NotExecutorOnly } from "./table-builder";
 
 // biome-ignore lint/suspicious/noExplicitAny: Dynamic tables — keys depend on user-defined schema.
 type Table = TableColumns<any>;
 
+// Method-form writes reject the executor-only brand exactly like the free-function
+// helpers (#742): a managed EntityTable is a rebuildable projection, so writing it
+// directly — free-function OR method-form — drifts the row past its event stream and
+// a rebuild wipes it. The permissive base stays (raw pgTables AND unmanaged entity
+// metas are not projections → writable); `& NotExecutorOnly` strips only branded
+// EntityTables (its `[EXECUTOR_ONLY]: true` violates the optional-never). Reads keep
+// the plain `Table` param.
+type WritableTable = (Table | EntityTableMeta) & NotExecutorOnly;
+
 /**
  * TenantDb scope modes:
  *
@@ -45,21 +56,15 @@ export type TenantDb = {
   ): Promise<readonly T[]>;
   fetchOne<T = Record<string, unknown>>(table: Table, where: WhereObject): Promise<T | undefined>;
   insertOne<T = Record<string, unknown>>(
-    table: Table,
+    table: WritableTable,
     values: Record<string, unknown>,
   ): Promise<T | undefined>;
   updateMany<T = Record<string, unknown>>(
-    table: Table,
+    table: WritableTable,
     set: Record<string, unknown>,
     where: WhereObject,
   ): Promise<readonly T[]>;
-  // Method-form writes (ctx.db.insertOne/updateMany/deleteMany) keep the erased
-  // Table param: the executor-only brand is enforced on the free-function
-  // helpers (the reflexive path all production writes take), while method-form
-  // on a branded table is covered by the guard-direct-entity-writes AST guard
-  // (P5) — branding it here would force every push+write test into casts for
-  // zero production benefit (no prod code writes a projection via method-form).
-  deleteMany(table: Table, where: WhereObject): Promise<void>;
+  deleteMany(table: WritableTable, where: WhereObject): Promise<void>;
 };
 
 // @cast-boundary tenant-db-row

package/src/observability/__tests__/observability.integration.test.ts

@@ -1,5 +1,6 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "bun:test";
 import { z } from "zod";
+import type { TableColumns } from "../../db/dialect";
 import { buildEntityTable } from "../../db/table-builder";
 import { createRegistry, defineFeature } from "../../engine";
 import type { AppContext, SaveContext } from "../../engine/types";
@@ -65,7 +66,9 @@ const todoEntity = {
 
 let postSaveInvocations = 0;
 const todoFeature = defineFeature("todo", (r) => {
-  const todoTable = buildEntityTable("todo", todoEntity);
+  // Brand (#742) is compile-time-only; the unbranded TableColumns view keeps the
+  // method-form insert (and its observability span) working — runtime shape is identical.
+  const todoTable: TableColumns = buildEntityTable("todo", todoEntity);
   r.entity("todo", todoEntity);
 
   r.writeHandler(