@cosmicdrift/kumiko-framework 0.165.1 → 0.165.3

package/README.md

@@ -79,7 +79,7 @@ export const taskFeature = defineFeature("tasks", (r) => {
 | Entry | What's in it |
 |---|---|
 | `@cosmicdrift/kumiko-framework/engine` | `defineFeature`, `createEntity`, field helpers, access rules, registry |
-| `@cosmicdrift/kumiko-framework/db` | `buildEntityTableMeta`, `createEventStoreExecutor`, migrations, tenant-db |
+| `@cosmicdrift/kumiko-framework/db` | `deriveEntityTableMeta`, `createEventStoreExecutor`, migrations, tenant-db |
 | `@cosmicdrift/kumiko-framework/event-store` | `events` table, `append`, `loadAggregate`, `loadAggregateAsOf` |
 | `@cosmicdrift/kumiko-framework/pipeline` | Dispatcher, event-dispatcher (AsyncDaemon), projection-rebuild, SSE + search consumers |
 | `@cosmicdrift/kumiko-framework/api` | `buildServer`, auth middleware, SSE route, error contract |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.165.1",
+  "version": "0.165.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>",
@@ -197,10 +197,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@cosmicdrift/kumiko-types": "^0.165.1"
+    "@cosmicdrift/kumiko-types": "^0.165.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.165.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.165.3",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/auth-routes-trusted-proxy.test.ts

@@ -128,10 +128,14 @@ describe("AuthRoutesConfig.trustedProxyHops", () => {
     expect(third.status).toBe(429);
   });
 
-  test("hops=1 with no XFF header at all falls back to unknown, not a throw", async () => {
+  test("hops=1 with no XFF and no X-Real-IP collapses distinct clients into unknown", async () => {
     const app = await buildApp({ trustedProxyHops: 1 });
-    const res = await app.request(verifyRequest(undefined));
-    expect(res.status).toBe(422);
+    // Three requests without either header must share the "unknown" bucket —
+    // a single 422 only proves "no throw", not the collapse (fw#1555#2).
+    const attempt = () => app.request(verifyRequest(undefined));
+    expect((await attempt()).status).toBe(422);
+    expect((await attempt()).status).toBe(422);
+    expect((await attempt()).status).toBe(429);
   });
 
   test("hops=1 with short/missing XFF uses x-real-ip so clients stay independent", async () => {

package/src/api/__tests__/sse-broker.test.ts

@@ -1,5 +1,14 @@
 import { describe, expect, mock, test } from "bun:test";
-import { createSseBroker, type SseEvent } from "../sse-broker";
+import { createSseBroker, type SseBroker, type SseEvent } from "../sse-broker";
+
+function requireAccessInvalidation(broker: SseBroker) {
+  const subscribe = broker.subscribeAccessInvalidation;
+  const publish = broker.publishAccessInvalidation;
+  if (!subscribe || !publish) {
+    throw new Error("createSseBroker must implement access-invalidation hooks");
+  }
+  return { subscribe, publish };
+}
 
 describe("SSE broker", () => {
   test("adds client and tracks count", () => {
@@ -57,59 +66,59 @@ describe("SSE broker", () => {
   });
 
   test("subscribeAccessInvalidation fires only listeners on the same user's channel", () => {
-    const broker = createSseBroker();
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
     const onInvalidateA = mock();
     const onInvalidateB = mock();
 
-    broker.subscribeAccessInvalidation("user-a", onInvalidateA);
-    broker.subscribeAccessInvalidation("user-b", onInvalidateB);
+    subscribe("user-a", onInvalidateA);
+    subscribe("user-b", onInvalidateB);
 
-    broker.publishAccessInvalidation("user-a");
+    publish("user-a");
 
     expect(onInvalidateA).toHaveBeenCalledTimes(1);
     expect(onInvalidateB).not.toHaveBeenCalled();
   });
 
   test("subscribeAccessInvalidation supports multiple listeners on the same user", () => {
-    const broker = createSseBroker();
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
     const first = mock();
     const second = mock();
 
-    broker.subscribeAccessInvalidation("user-a", first);
-    broker.subscribeAccessInvalidation("user-a", second);
-    broker.publishAccessInvalidation("user-a");
+    subscribe("user-a", first);
+    subscribe("user-a", second);
+    publish("user-a");
 
     expect(first).toHaveBeenCalledTimes(1);
     expect(second).toHaveBeenCalledTimes(1);
   });
 
   test("unsubscribe (returned closure) stops further delivery", () => {
-    const broker = createSseBroker();
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
     const onInvalidate = mock();
 
-    const unsubscribe = broker.subscribeAccessInvalidation("user-a", onInvalidate);
+    const unsubscribe = subscribe("user-a", onInvalidate);
     unsubscribe();
-    broker.publishAccessInvalidation("user-a");
+    publish("user-a");
 
     expect(onInvalidate).not.toHaveBeenCalled();
   });
 
   test("a fired listener can unsubscribe itself without skipping other listeners", () => {
-    const broker = createSseBroker();
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
     let unsubscribeSelf: () => void = () => {};
     const self = mock(() => unsubscribeSelf());
     const other = mock();
 
-    unsubscribeSelf = broker.subscribeAccessInvalidation("user-a", self);
-    broker.subscribeAccessInvalidation("user-a", other);
-    broker.publishAccessInvalidation("user-a");
+    unsubscribeSelf = subscribe("user-a", self);
+    subscribe("user-a", other);
+    publish("user-a");
 
     expect(self).toHaveBeenCalledTimes(1);
     expect(other).toHaveBeenCalledTimes(1);
   });
 
   test("publishAccessInvalidation to a user with no listeners does nothing", () => {
-    const broker = createSseBroker();
-    expect(() => broker.publishAccessInvalidation("nobody-listening")).not.toThrow();
+    const { publish } = requireAccessInvalidation(createSseBroker());
+    expect(() => publish("nobody-listening")).not.toThrow();
   });
 });

package/src/api/routes.ts

@@ -19,9 +19,9 @@ import { patAllows } from "./pat-scope";
 import { requestContext } from "./request-context";
 import { SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route";
 
-// SSE frame event names for POST /api/stream (framework-owned; dispatcher-live
-// has no dependency on this package and keeps its own copy in sse-stream.ts —
-// a drift between the two fails the real-HTTP frame assertions in api.test.ts).
+// SSE frame event names for POST /api/stream. Parallel definition lives in
+// @cosmicdrift/kumiko-headless (dispatcher-live imports that one) — framework
+// cannot depend on headless for four string literals.
 export const StreamFrame = {
   chunk: "chunk",
   ping: "ping",

package/src/api/sse-broker.ts

@@ -18,18 +18,18 @@ export type SseBroker = {
   pushToChannel(channel: string, event: SseEvent): void;
   getClientCount(channel: string): number;
   getTotalClientCount(): number;
-  // Internal (non-SSE-client) subscription, e.g. dispatch-stream watching
-  // for mid-stream access revocation. Kept separate from addClient/
-  // pushToChannel: those count towards getClientCount/getTotalClientCount
-  // (real SSE connections) and their send/close shape doesn't fit a plain
-  // callback listener. Returns an unsubscribe function.
-  subscribeAccessInvalidation(userId: string, onInvalidate: () => void): () => void;
-  publishAccessInvalidation(userId: string): void;
+  // Separate from addClient so it doesn't count towards getClientCount.
+  // Optional: additive for external/test SseBroker impls (call sites use?.).
+  subscribeAccessInvalidation?(userId: string, onInvalidate: () => void): () => void;
+  publishAccessInvalidation?(userId: string): void;
 };
 
 export function createSseBroker(): SseBroker {
+  // ponytail: in-process only — publishAccessInvalidation does not fan out via
+  // Redis. Multi-replica deployments will not revoke SSE streams on other pods
+  // (security control is single-node). Upgrade: Redis pub/sub on userAccessChannel.
   const channels = new Map<string, Map<string, SseClient>>();
-  const accessInvalidationListeners = new Map<string, Map<string, () => void>>();
+  const accessInvalidationListeners = new Map<string, Set<() => void>>();
 
   function getOrCreateChannel(channel: string): Map<string, SseClient> {
     let clients = channels.get(channel);
@@ -79,18 +79,17 @@ export function createSseBroker(): SseBroker {
 
     subscribeAccessInvalidation(userId, onInvalidate) {
       const channel = userAccessChannel(userId);
-      const listenerId = generateId();
       let listeners = accessInvalidationListeners.get(channel);
       if (!listeners) {
-        listeners = new Map();
+        listeners = new Set();
         accessInvalidationListeners.set(channel, listeners);
       }
-      listeners.set(listenerId, onInvalidate);
+      listeners.add(onInvalidate);
       return () => {
         const current = accessInvalidationListeners.get(channel);
         // skip: already unsubscribed (e.g. stream ended after a publish already fired)
         if (!current) return;
-        current.delete(listenerId);
+        current.delete(onInvalidate);
         if (current.size === 0) accessInvalidationListeners.delete(channel);
       };
     },
@@ -102,7 +101,7 @@ export function createSseBroker(): SseBroker {
       if (!listeners) return;
       // Snapshot before iterating — a fired listener unsubscribes itself,
       // which would mutate `listeners` mid-iteration otherwise.
-      for (const onInvalidate of [...listeners.values()]) {
+      for (const onInvalidate of [...listeners]) {
         onInvalidate();
       }
     },

package/src/bun-db/query.ts

@@ -67,7 +67,7 @@ function isEntityTableMeta(v: unknown): v is EntityTableMeta {
 // 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
+//  - deriveEntityTableMeta / defineUnmanagedTable return a plain meta with no
 //    handle-spread, so its structural shape is itself unshadowable.
 export function asEntityTableMeta(table: unknown): EntityTableMeta | undefined {
   if (table === null || typeof table !== "object") return undefined;
@@ -252,7 +252,7 @@ export function extractTableInfo(table: TableLike): TableInfo {
   if (!meta) {
     throw new Error(
       "bun-db.extractTableInfo: table is not a kumiko EntityTableMeta — " +
-        "build it via buildEntityTable / buildEntityTableMeta / table().",
+        "build it via buildEntityTable / deriveEntityTableMeta / table().",
     );
   }
   const colByField = new Map<string, string>();

package/src/crypto/index.ts

@@ -61,6 +61,7 @@ export {
 } from "./request-kms-cache";
 export {
   collectPiiSubjectFields,
+  collectSearchableSubjectFields,
   type ResolveSubjectOptions,
   resolveSubjectForField,
   SubjectResolutionError,

package/src/crypto/subject-resolver.ts

@@ -89,3 +89,18 @@ export function collectPiiSubjectFields(entity: EntityDefinition): readonly stri
     )
     .map(([name]) => name);
 }
+
+/** Subject-annotated fields that may be plaintext in the derived search index (#1610). */
+export function collectSearchableSubjectFields(entity: EntityDefinition): readonly string[] {
+  return Object.entries(entity.fields)
+    .filter(([, field]) => {
+      const subject =
+        ("userOwned" in field && field.userOwned !== undefined) ||
+        ("tenantOwned" in field && field.tenantOwned === true) ||
+        ("pii" in field && field.pii === true);
+      if (!subject) return false;
+      if ("sensitive" in field && field.sensitive === true) return false;
+      return "searchable" in field && field.searchable === true;
+    })
+    .map(([name]) => name);
+}

package/src/db/__tests__/decimal-field.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { createDecimalField, createEntity } from "../../engine/factories";
 import { fieldToZod } from "../../engine/schema-builder";
-import { buildEntityTableMeta } from "../entity-table-meta";
+import { deriveEntityTableMeta } from "../entity-table-meta";
 import { coerceRow, extractTableInfo } from "../query";
 import { renderTableDdl } from "../render-ddl";
 import { buildEntityTable } from "../table-builder";
@@ -25,7 +25,7 @@ const entity = createEntity({
 describe("decimal field — column + DDL", () => {
   test("maps to numeric(precision,scale) with required→NOT NULL", () => {
     const cols = new Map(
-      buildEntityTableMeta("decimalProbe", entity).columns.map((c) => [c.name, c]),
+      deriveEntityTableMeta("decimalProbe", entity).columns.map((c) => [c.name, c]),
     );
     expect(cols.get("sum")?.pgType).toBe("numeric(14,2)");
     expect(cols.get("interest")?.pgType).toBe("numeric(6,4)");
@@ -35,7 +35,7 @@ describe("decimal field — column + DDL", () => {
   });
 
   test("renders real numeric(p,s) DDL", () => {
-    const ddl = renderTableDdl(buildEntityTableMeta("decimalProbe", entity)).join("\n");
+    const ddl = renderTableDdl(deriveEntityTableMeta("decimalProbe", entity)).join("\n");
     expect(ddl).toContain('"interest" numeric(6,4) NOT NULL');
     expect(ddl).toContain('"rate" numeric(12,2)');
   });

package/src/db/__tests__/entity-table-meta-source.test.ts

@@ -1,4 +1,4 @@
-// #1210: buildEntityTableMeta() hardcoded source: "managed", so unmanaged
+// #1210: deriveEntityTableMeta() hardcoded source: "managed", so unmanaged
 // direct-write stores (store_user_sessions, store_api_tokens, mail sync/seen
 // cursors) were misclassified as rebuildable event-sourced projections — a
 // destructive column change would DROP+rebuild-from-events tables that have
@@ -8,7 +8,7 @@
 
 import { describe, expect, test } from "bun:test";
 import { createEntity, createTextField } from "../../engine";
-import { buildEntityTableMeta } from "../entity-table-meta";
+import { defineUnmanagedTable, deriveEntityTableMeta } from "../entity-table-meta";
 import { diffSnapshots, snapshotFromMetas } from "../migrate-generator";
 
 const entity = createEntity({
@@ -19,14 +19,14 @@ const entity = createEntity({
   },
 });
 
-describe("buildEntityTableMeta — options.source (#1210)", () => {
+describe("deriveEntityTableMeta — options.source (#1210)", () => {
   test("defaults to managed when omitted", () => {
-    expect(buildEntityTableMeta("source-probe", entity).source).toBe("managed");
+    expect(deriveEntityTableMeta("source-probe", entity).source).toBe("managed");
   });
 
   test("options.source: 'unmanaged' changes only source, columns + piiSubjectFields stay identical", () => {
-    const managed = buildEntityTableMeta("source-probe", entity);
-    const unmanaged = buildEntityTableMeta("source-probe", entity, { source: "unmanaged" });
+    const managed = deriveEntityTableMeta("source-probe", entity);
+    const unmanaged = deriveEntityTableMeta("source-probe", entity, { source: "unmanaged" });
 
     expect(managed.source).toBe("managed");
     expect(unmanaged.source).toBe("unmanaged");
@@ -37,9 +37,9 @@ describe("buildEntityTableMeta — options.source (#1210)", () => {
   });
 
   test("flipping an existing table's meta to unmanaged produces an empty migration diff", () => {
-    const prevSnapshot = snapshotFromMetas([buildEntityTableMeta("source-probe", entity)]);
+    const prevSnapshot = snapshotFromMetas([deriveEntityTableMeta("source-probe", entity)]);
     const nextSnapshot = snapshotFromMetas([
-      buildEntityTableMeta("source-probe", entity, { source: "unmanaged" }),
+      deriveEntityTableMeta("source-probe", entity, { source: "unmanaged" }),
     ]);
 
     const diff = diffSnapshots(prevSnapshot, nextSnapshot);
@@ -47,4 +47,39 @@ describe("buildEntityTableMeta — options.source (#1210)", () => {
     expect(diff.droppedTables).toEqual([]);
     expect(diff.changedTables).toEqual([]);
   });
+
+  test("deprecated buildEntityTableMeta alias still works", async () => {
+    const { buildEntityTableMeta } = await import("../entity-table-meta");
+    expect(buildEntityTableMeta("source-probe", entity).source).toBe("managed");
+  });
+});
+
+describe("unmanaged builders reject read_ prefix (#1208)", () => {
+  test("deriveEntityTableMeta(..., { source: unmanaged }) with read_ table throws", () => {
+    const readEntity = createEntity({
+      table: "read_source_probe",
+      fields: { userId: createTextField({ required: true }) },
+    });
+    expect(() =>
+      deriveEntityTableMeta("source-probe", readEntity, { source: "unmanaged" }),
+    ).toThrow(/the "read_" prefix is reserved/);
+  });
+
+  test("default toTableName (read_*) + unmanaged throws", () => {
+    const noTable = createEntity({
+      fields: { userId: createTextField({ required: true }) },
+    });
+    expect(() => deriveEntityTableMeta("source-probe", noTable, { source: "unmanaged" })).toThrow(
+      /the "read_" prefix is reserved/,
+    );
+  });
+
+  test("defineUnmanagedTable with read_ tableName throws", () => {
+    expect(() =>
+      defineUnmanagedTable({
+        tableName: "read_oops",
+        columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
+      }),
+    ).toThrow(/the "read_" prefix is reserved/);
+  });
 });

package/src/db/__tests__/migrate-runner.test.ts

@@ -34,6 +34,14 @@ describe("splitSqlStatements", () => {
     expect(splitSqlStatements(sql)).toEqual(['CREATE TABLE "a" ("id" uuid);']);
   });
 
+  test("block comment leaves a space so adjacent tokens do not fuse", () => {
+    expect(splitSqlStatements("SELECT a/*x*/AS b;")).toEqual(["SELECT a AS b;"]);
+  });
+
+  test("nested block comments close only at matching depth (Postgres)", () => {
+    expect(splitSqlStatements("/* a /* b */ c */ SELECT 1;")).toEqual(["SELECT 1;"]);
+  });
+
   test("a block-comment opener inside a line comment does not swallow the next statement", () => {
     const sql = `
       -- note: see /* details below
@@ -69,7 +77,17 @@ describe("splitSqlStatements", () => {
 
   test("throws fail-loud on an unterminated block comment instead of silently dropping statements", () => {
     const sql = `/* oops\nCREATE TABLE "a" ("id" uuid);`;
-    expect(() => splitSqlStatements(sql)).toThrow();
+    expect(() => splitSqlStatements(sql)).toThrow(/unterminated blockComment/);
+  });
+
+  test("throws fail-loud on an unterminated single-quoted string", () => {
+    const sql = `INSERT INTO "a" ("v") VALUES ('oops;`;
+    expect(() => splitSqlStatements(sql)).toThrow(/unterminated singleQuote/);
+  });
+
+  test("throws fail-loud on an unterminated double-quoted identifier", () => {
+    const sql = `CREATE TABLE "weird;`;
+    expect(() => splitSqlStatements(sql)).toThrow(/unterminated doubleQuote/);
   });
 
   test("a trailing line comment without a newline terminates cleanly", () => {

package/src/db/__tests__/table-builder-meta-lockstep.test.ts

@@ -2,12 +2,12 @@ import { describe, expect, test } from "bun:test";
 import { createEntity } from "../../engine/factories";
 import { sql } from "../dialect";
 import type { ColumnMeta, IndexMeta } from "../entity-table-meta";
-import { buildEntityTableMeta } from "../entity-table-meta";
+import { deriveEntityTableMeta } from "../entity-table-meta";
 import { asEntityTableMeta } from "../query";
 import { buildEntityTable } from "../table-builder";
 
 // Lock-step-Guard: buildEntityTable (Runtime-/Test-Stack-Pfad, Meta am
-// KUMIKO_META_SYMBOL) und buildEntityTableMeta (Migrations-Pfad) müssen
+// KUMIKO_META_SYMBOL) und deriveEntityTableMeta (Migrations-Pfad) müssen
 // für dieselbe EntityDefinition identische Spalten + Indexes produzieren.
 // Drift hier = Migration und Prod-Tabelle (bzw. collectTableMetas-Output)
 // gehen auseinander — gefunden als #255-Follow-up: select/number/bigInt
@@ -33,9 +33,9 @@ function byName<T extends { name: string }>(items: readonly T[]): readonly T[] {
   return [...items].sort((a, b) => a.name.localeCompare(b.name));
 }
 
-describe("buildEntityTable ↔ buildEntityTableMeta lock-step", () => {
+describe("buildEntityTable ↔ deriveEntityTableMeta lock-step", () => {
   const fromBuilder = asEntityTableMeta(buildEntityTable("lockstepProbe", entityWithDefaults));
-  const fromMeta = buildEntityTableMeta("lockstepProbe", entityWithDefaults);
+  const fromMeta = deriveEntityTableMeta("lockstepProbe", entityWithDefaults);
 
   test("builder table carries an EntityTableMeta", () => {
     expect(fromBuilder).toBeDefined();
@@ -92,7 +92,7 @@ describe("lock-step — softDelete + explizite Indexes", () => {
   const fromBuilder = asEntityTableMeta(
     buildEntityTable("lockstepProbeSd", entityWithSoftDeleteAndIndexes),
   );
-  const fromMeta = buildEntityTableMeta("lockstepProbeSd", entityWithSoftDeleteAndIndexes);
+  const fromMeta = deriveEntityTableMeta("lockstepProbeSd", entityWithSoftDeleteAndIndexes);
 
   test("identical columns inkl. softDelete-Spalten", () => {
     expect(byName<ColumnMeta>(fromBuilder?.columns ?? [])).toEqual(
@@ -125,7 +125,7 @@ describe("lock-step — lookupable / blind-index (#818)", () => {
   const fromBuilder = asEntityTableMeta(
     buildEntityTable("lockstepProbeBidx", entityWithLookupable),
   );
-  const fromMeta = buildEntityTableMeta("lockstepProbeBidx", entityWithLookupable);
+  const fromMeta = deriveEntityTableMeta("lockstepProbeBidx", entityWithLookupable);
 
   test("identical columns inkl. nullable bidx-Spalte", () => {
     expect(byName<ColumnMeta>(fromBuilder?.columns ?? [])).toEqual(

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

@@ -3,7 +3,7 @@ import { createEntity, createTextField } from "../../engine";
 import { testTenantId } from "../../stack";
 import type { DbRunner } from "../connection";
 import type { TableColumns } from "../dialect";
-import { buildEntityTableMeta } from "../entity-table-meta";
+import { deriveEntityTableMeta } from "../entity-table-meta";
 import { buildEntityTable } from "../table-builder";
 import { createTenantDb } from "../tenant-db";
 
@@ -123,16 +123,16 @@ describe("tenant-db WHERE merge — narrowing within the enforced scope", () =>
 });
 
 // Root-cause regression for the cross-tenant leak fixed in hasTenantColumn:
-// unmanaged direct-write stores (buildEntityTableMeta, e.g. userSessionTable,
+// unmanaged direct-write stores (deriveEntityTableMeta, e.g. userSessionTable,
 // apiTokenTable) store tenantId as a snake_case column-meta entry, not a
 // direct `table.tenantId` property — a naive property check silently treated
 // them as tenant-less and skipped the WHERE-scope entirely.
-describe("tenant-db WHERE merge — unmanaged EntityTableMeta tables (buildEntityTableMeta)", () => {
+describe("tenant-db WHERE merge — unmanaged EntityTableMeta tables (deriveEntityTableMeta)", () => {
   const unmanagedEntity = createEntity({
     table: "merge_meta_items",
     fields: { tenantId: createTextField({ required: true }), name: createTextField() },
   });
-  const unmanagedTable = buildEntityTableMeta("merge-meta-item", unmanagedEntity);
+  const unmanagedTable = deriveEntityTableMeta("merge-meta-item", unmanagedEntity);
 
   test("selectMany still applies the tenant scope (pre-fix: no WHERE at all)", async () => {
     const captured: Captured[] = [];

package/src/db/collect-table-metas.ts

@@ -9,7 +9,7 @@ import type { FeatureDefinition } from "../engine/types";
 import { compareByCodepoint } from "../utils";
 import {
   assertBackingTableSuperset,
-  buildEntityTableMeta,
+  deriveEntityTableMeta,
   type EntityTableMeta,
 } from "./entity-table-meta";
 import { enumerateFeatureTableSources } from "./feature-table-sources";
@@ -36,10 +36,10 @@ export function collectTableMetas(
   const byName = new Map<string, { meta: EntityTableMeta; origin: string }>();
 
   // Pass 1: kanonische Schema-Quellen, identisch zum bisherigen Template-
-  // Verhalten (gleiche Reihenfolge, gleiche buildEntityTableMeta-Optionen).
+  // Verhalten (gleiche Reihenfolge, gleiche deriveEntityTableMeta-Optionen).
   for (const feature of features) {
     for (const [name, ent] of Object.entries(feature.entities ?? {})) {
-      const fieldMeta = buildEntityTableMeta(name, ent, { relations: feature.relations[name] });
+      const fieldMeta = deriveEntityTableMeta(name, ent, { relations: feature.relations[name] });
       // Backing table wins: it's the physical DDL truth for ride-along columns/
       // indexes the field-DSL can't express (secrets' envelope). Validated as a
       // superset of the field-derived meta so a field/table disagreement throws.

package/src/db/entity-table-meta.ts

@@ -1,22 +1,20 @@
-// EntityTableMeta — plain-data Schema-Meta für eine Read-Model-Tabelle.
-// Single source of truth statt verheirateter drizzle-pgTable-Builder.
+// EntityTableMeta — plain-data schema meta for a read-model table.
+// Single source of truth instead of a married drizzle pgTable builder.
 //
-// Phase 3a (Drizzle-Replacement Plan): Type + Generator existieren parallel
-// zu buildEntityTable. Konsumenten bleiben auf EntityTable (via Adapter
-// `entityTableMetaToEntityTable`), bis Phase 4 die Query-API auf Bun.sql
-// umstellt.
+// Phase 3a (Drizzle-Replacement Plan): type + generator exist in parallel
+// with buildEntityTable. Consumers stay on EntityTable (via adapter
+// `entityTableMetaToEntityTable`) until Phase 4 moves the query API to Bun.sql.
 //
-// Designed für zwei Quellen:
-//   1. **Managed** — EntityDefinition via buildEntityTableMeta(name, entity).
-//      Standard-Pfad mit base-columns (id, tenant_id, version, inserted_at,
-//      modified_at, inserted_by_id, modified_by_id, ggf. softDelete-Cols),
-//      automatischer tenant_id-Index, audit-fähig.
-//   2. **Unmanaged** — defineUnmanagedTable(input). Escape-Hatch für Tabellen
-//      die NICHT durch das Entity-System gemanagt werden — keine erzwungenen
-//      base-columns, kein Standard-Audit-Trail. App-Author trägt Verantwortung
-//      für Tenant-Scoping, Version-Tracking, audit-by-Spalten. Verwendung
-//      auf Sondercases beschränken (child-projection-tables ohne tenant,
-//      append-only-logs mit serial PK, aggregate-ID ohne DEFAULT, …).
+// Two sources:
+//   1. **Managed** — EntityDefinition via deriveEntityTableMeta(name, entity).
+//      Standard path with base columns (id, tenant_id, version, inserted_at,
+//      modified_at, inserted_by_id, modified_by_id, optional softDelete cols),
+//      automatic tenant_id index, audit-capable. Defaults to source: "managed".
+//   2. **Unmanaged** — defineUnmanagedTable(input), or
+//      deriveEntityTableMeta(..., { source: "unmanaged" }) when you still want
+//      entity-shaped base columns. Escape hatch: no forced audit trail for the
+//      hand-built path; app author owns tenant scoping / versioning. Prefer a
+//      `store_` table name — `read_` is reserved for managed projections (#1208/#1220).
 
 import { collectPiiSubjectFields } from "../crypto";
 import type { EntityDefinition, EntityIndexDef, FieldDefinition } from "../engine/types";
@@ -232,12 +230,25 @@ export function resolveTableName(
   return `${featureName}_${baseName}`;
 }
 
-export function buildEntityTableMeta(
+/**
+ * Derive EntityTableMeta from an EntityDefinition (base columns + field DDL).
+ * Defaults to `source: "managed"` (rebuildable projection). For direct-write
+ * stores pass `{ source: "unmanaged" }` and use a non-`read_` table name
+ * (convention: `store_*`) — or build columns by hand with `defineUnmanagedTable`.
+ *
+ * Named `derive*` (not `build*Meta`) so it is not mistaken for the unmanaged
+ * escape hatch (#1208).
+ */
+export function deriveEntityTableMeta(
   entityName: string,
   entity: EntityDefinition,
   options?: BuildEntityTableMetaOptions,
 ): EntityTableMeta {
   const tableName = resolveTableName(entityName, entity, options?.featureName);
+  const source = options?.source ?? "managed";
+  if (source === "unmanaged") {
+    assertUnmanagedTableName(tableName, "deriveEntityTableMeta");
+  }
   const idType = entity.idType ?? "uuid";
 
   // Base-columns first, then user-fields. User-fields with the same
@@ -349,24 +360,14 @@ export function buildEntityTableMeta(
     tableName,
     columns,
     indexes,
-    source: options?.source ?? "managed",
+    source,
     ...(piiSubjectFields.length > 0 && { piiSubjectFields }),
   };
 }
 
-// Escape-Hatch für Tabellen die NICHT durch das Entity-System gemanagt
-// werden. Kein Audit-Trail (keine version, inserted_at, modified_by etc.),
-// kein automatischer tenant_id-Index, kein softDelete-Support.
-//
-// **Vorsicht-vor-Use:** wenn du das hier benutzt, gibst du das Standard-
-// Audit-Pattern auf. Begründe im Code WARUM (child-projection ohne tenant-
-// scope, aggregate-id-PK ohne DEFAULT, append-only-log mit serial PK,
-// performance-critical hot-path ohne version-check, …). Reviewer sollten
-// jede neue defineUnmanagedTable-Stelle prüfen.
-//
-// Heutige use-cases im framework:
-//   - `store_delivery_attempts` — id kommt aus dem Aggregate-Stream
-//   - `store_job_run_logs` — child-table, serial PK, kein tenant-scope
+/** @deprecated Use {@link deriveEntityTableMeta} — the old name read as an unmanaged escape hatch (#1208). */
+export const buildEntityTableMeta = deriveEntityTableMeta;
+
 function sqlExpressionText(where: unknown): string | undefined {
   if (
     typeof where === "object" &&
@@ -420,7 +421,12 @@ function columnsByNameMeta(meta: EntityTableMeta): Map<string, ColumnMeta> {
   return m;
 }
 
+/**
+ * Hand-built EntityTableMeta for direct-write stores (no entity base columns).
+ * Prefer a `store_*` table name; `read_` is reserved for managed projections (#1220).
+ */
 export function defineUnmanagedTable(input: UnmanagedTableInput): EntityTableMeta {
+  assertUnmanagedTableName(input.tableName, "defineUnmanagedTable");
   return {
     tableName: input.tableName,
     columns: input.columns,
@@ -431,3 +437,14 @@ export function defineUnmanagedTable(input: UnmanagedTableInput): EntityTableMet
     source: "unmanaged",
   };
 }
+
+function assertUnmanagedTableName(tableName: string, via: string): void {
+  if (tableName.startsWith("read_")) {
+    throw new Error(
+      `${via}("${tableName}"): the "read_" prefix is reserved for managed ` +
+        `r.entity()/r.projection() tables. Unmanaged direct-write stores need a ` +
+        `distinct name (convention: "store_${tableName.slice("read_".length)}"). ` +
+        `See #1208/#1220.`,
+    );
+  }
+}