@cosmicdrift/kumiko-framework 0.165.1 → 0.165.2

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.2",
   "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.2"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.165.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.165.2",
     "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/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,16 +18,15 @@ 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.
+  // Separate from addClient so it doesn't count towards getClientCount.
   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>>();
 

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/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,10 @@ 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("a block-comment opener inside a line comment does not swallow the next statement", () => {
     const sql = `
       -- note: see /* details below
@@ -69,7 +73,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.`,
+    );
+  }
+}

package/src/db/index.ts

@@ -59,7 +59,11 @@ export type {
   PgType,
   UnmanagedTableInput,
 } from "./entity-table-meta";
-export { buildEntityTableMeta, defineUnmanagedTable } from "./entity-table-meta";
+export {
+  buildEntityTableMeta,
+  defineUnmanagedTable,
+  deriveEntityTableMeta,
+} from "./entity-table-meta";
 export type {
   EntityLifecycleVerb,
   EventStoreExecutor,

package/src/db/migrate-runner.ts

@@ -74,16 +74,7 @@ CREATE TABLE IF NOT EXISTS "_kumiko_migrations" (
 )
 `.trim();
 
-// Splits SQL-file text into individual statements on top-level `;`. A plain
-// `text.split(";")` breaks the moment a `--` line comment or `/* */` block
-// comment contains a semicolon (#1542) — it splits mid-comment before the
-// comment is ever stripped. This scans char-by-char tracking whether we're
-// inside a line comment, block comment, single-quoted string, or
-// double-quoted identifier, so `;` only ends a statement in plain SQL text;
-// comments are dropped, quoted/identifier content (incl. `''`/`""` escapes)
-// is kept verbatim. Does not handle dollar-quoted (`$$...$$`) bodies — none
-// of this repo's checked-in migrations use them; add that state if one ever
-// does.
+// Plain `;`-split breaks on `;` inside comments/string literals (#1542).
 type SqlScanState = "normal" | "lineComment" | "blockComment" | "singleQuote" | "doubleQuote";
 
 export function splitSqlStatements(sqlText: string): readonly string[] {
@@ -106,6 +97,8 @@ export function splitSqlStatements(sqlText: string): readonly string[] {
       if (ch === "*" && next === "/") {
         state = "normal";
         i++;
+        // Keep a space so `a/*x*/AS` does not become `aAS`.
+        current += " ";
       }
       continue;
     }
@@ -163,6 +156,8 @@ export function splitSqlStatements(sqlText: string): readonly string[] {
     current += ch;
   }
   if (state === "blockComment" || state === "singleQuote" || state === "doubleQuote") {
+    // Does not track dollar-quoted (`$$...$$`) bodies — none of this repo's
+    // migrations use them; add that state if one ever does.
     throw new Error(
       `splitSqlStatements: unterminated ${state} — migration SQL is malformed, refusing to split`,
     );

package/src/db/table-builder.ts

@@ -526,7 +526,7 @@ export function buildEntityTable<E extends EntityDefinition>(
         }
       }
       // lookupable-Felder: Index auf der bidx-Spalte (lock-step mit
-      // buildEntityTableMeta).
+      // deriveEntityTableMeta).
       const bidxFieldByField = new Map<string, string>();
       for (const [name, field] of Object.entries(entity.fields)) {
         if (field.type !== "text" || field.lookupable !== true) continue;
@@ -558,7 +558,7 @@ export function buildEntityTable<E extends EntityDefinition>(
         }
         indexes[indexName] = chain;
         // Partielles bidx-Pendant für unique-Indices über lookupable-Spalten
-        // (lock-step mit buildEntityTableMeta).
+        // (lock-step mit deriveEntityTableMeta).
         if (def.unique === true && def.where === undefined) {
           const bidxFieldNames = def.columns.map((c) => bidxFieldByField.get(c) ?? c);
           if (bidxFieldNames.some((c, i) => c !== def.columns[i])) {

package/src/db/tenant-db.ts

@@ -30,7 +30,7 @@ function tableNameOf(table: Table): string {
 }
 
 // Checks the canonical EntityTableMeta (branded EntityTable's KUMIKO_META_SYMBOL
-// or a plain buildEntityTableMeta/defineUnmanagedTable result), not a direct
+// or a plain deriveEntityTableMeta/defineUnmanagedTable result), not a direct
 // `table.tenantId` property read — the latter only exists on branded EntityTables
 // and silently returned false (no tenant filter!) for plain EntityTableMeta
 // tables like unmanaged direct-write stores, e.g. userSessionTable.

package/src/engine/__tests__/store-table.test.ts

@@ -7,8 +7,8 @@
 
 import { describe, expect, test } from "bun:test";
 import {
-  buildEntityTableMeta,
   defineUnmanagedTable,
+  deriveEntityTableMeta,
   resolveTableName,
 } from "../../db/entity-table-meta";
 import { defineFeature } from "../define-feature";
@@ -67,7 +67,7 @@ describe("r.storeTable — declaration", () => {
       table: "rt_probe_managed",
       fields: { name: createTextField() },
     });
-    const managedMeta = buildEntityTableMeta("rt-probe-managed", managedEntity);
+    const managedMeta = deriveEntityTableMeta("rt-probe-managed", managedEntity);
     expect(() =>
       defineFeature("probe", (r) => {
         r.storeTable(managedMeta, { reason: "test" });
@@ -75,14 +75,11 @@ describe("r.storeTable — declaration", () => {
     ).toThrow(/requires source: "unmanaged"/);
   });
 
-  test("rejects a table name with the reserved read_ prefix (#1220)", () => {
-    const readPrefixed = defineUnmanagedTable({
-      tableName: "read_rt_probe",
-      columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
-    });
+  test("rejects a table name with the reserved read_ prefix (#1220/#1208)", () => {
     expect(() =>
-      defineFeature("probe", (r) => {
-        r.storeTable(readPrefixed, { reason: "test" });
+      defineUnmanagedTable({
+        tableName: "read_rt_probe",
+        columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
       }),
     ).toThrow(/the "read_" prefix is reserved/);
   });
@@ -195,9 +192,9 @@ describe("createRegistry — store tables with PII-annotated fields (#820)", ()
       ip: createTextField({ userOwned: { ownerField: "userId" } }),
     },
   });
-  const piiMeta = buildEntityTableMeta("rt-pii-probe", piiEntity, { source: "unmanaged" });
+  const piiMeta = deriveEntityTableMeta("rt-pii-probe", piiEntity, { source: "unmanaged" });
 
-  test("buildEntityTableMeta records the subject-annotated field names", () => {
+  test("deriveEntityTableMeta records the subject-annotated field names", () => {
     expect(piiMeta.piiSubjectFields).toEqual(["ip"]);
   });
 

package/src/engine/constants.ts

@@ -103,10 +103,6 @@ export function tenantChannel(tenantId: TenantId): string {
   return `tenant:${tenantId}`;
 }
 
-// Access-invalidation channel key for a single user's live streams. Both
-// the subscribe side (dispatch-stream.ts) and the publish side (session-
-// revoke / tenant-membership consumers, issue #1559/#1560) must derive the
-// key through this helper — never build the string inline on either side.
 export function userAccessChannel(userId: string): string {
   return `user:${userId}:access`;
 }

package/src/engine/feature-ast/extractors/round5.ts

@@ -100,7 +100,7 @@ export function extractStoreTable(
   sourceFile: SourceFile,
 ): ExtractOutput<never> {
   // The meta argument is always a factory call (defineUnmanagedTable /
-  // buildEntityTableMeta) or a captured identifier — never an inline literal,
+  // deriveEntityTableMeta) or a captured identifier — never an inline literal,
   // so there is nothing to extract statically. A clean ParseError (not
   // UnknownPattern) marks it design-time-unreadable, like entity-by-identifier.
   return fail(

package/src/engine/feature-ui-extensions.ts

@@ -454,7 +454,7 @@ export function buildUiExtensionsMethods<TName extends string>(
         throw new Error(
           `[Feature ${name}] r.storeTable("${tableName}") was given an EntityTableMeta with ` +
             `source: "${meta.source}". r.storeTable() requires source: "unmanaged" (via ` +
-            `defineUnmanagedTable(), or buildEntityTableMeta(..., { source: "unmanaged" })) — ` +
+            `defineUnmanagedTable(), or deriveEntityTableMeta(..., { source: "unmanaged" })) — ` +
             `otherwise the migration generator will treat schema drift on this table as safe ` +
             `to DROP+rebuild, wiping any direct-write data.`,
         );

package/src/engine/registry-state.ts

@@ -1,5 +1,5 @@
 import { applyEntityEvent } from "../db/apply-entity-event";
-import { assertBackingTableSuperset, buildEntityTableMeta } from "../db/entity-table-meta";
+import { assertBackingTableSuperset, deriveEntityTableMeta } from "../db/entity-table-meta";
 import { asEntityTableMeta } from "../db/query";
 import { buildEntityTable } from "../db/table-builder";
 import { type QnType, qualifyEntityName } from "./qualified-name";
@@ -143,7 +143,7 @@ function resolveBackingTable(
         "EntityTableMeta — build it via table() / buildEntityTable.",
     );
   }
-  assertBackingTableSuperset(entityName, buildEntityTableMeta(entityName, entity), tableMeta);
+  assertBackingTableSuperset(entityName, deriveEntityTableMeta(entityName, entity), tableMeta);
   return backingTable as ProjectionDefinition["table"];
 }
 

package/src/engine/validate-projection-allowlist.ts

@@ -71,7 +71,7 @@ function resolveTableNameFromStep(table: unknown): string {
       const metaName = (meta as Record<string, unknown>)["tableName"];
       if (typeof metaName === "string") return metaName;
     }
-    // Plain meta (buildEntityTableMeta / defineUnmanagedTable — no handle-spread).
+    // Plain meta (deriveEntityTableMeta / defineUnmanagedTable — no handle-spread).
     if (
       "source" in table &&
       "tableName" in table &&

package/src/migrations/__tests__/kumiko-drift.integration.test.ts

@@ -8,7 +8,7 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
-import { buildEntityTableMeta } from "../../db/entity-table-meta";
+import { deriveEntityTableMeta } from "../../db/entity-table-meta";
 import { generateMigration, writeSnapshotJson } from "../../db/migrate-generator";
 import {
   baselineMigrations,
@@ -200,7 +200,7 @@ describe("kumiko-drift end-to-end (generate → apply → gate)", () => {
       table: "kdrift_gen",
       fields: { name: createTextField({ required: true }) },
     });
-    const meta = buildEntityTableMeta("kdriftGen", entity);
+    const meta = deriveEntityTableMeta("kdriftGen", entity);
     const result = generateMigration({
       metas: [meta],
       prevSnapshot: null,

package/src/migrations/projection-table-index.ts

@@ -3,7 +3,7 @@
 // rebuild-Marker → mappt Tabellen auf Projektionen → rebuildProjection).
 //
 // Drizzle-frei: der Tabellen-Name kommt aus dem kumiko-Symbol das
-// buildEntityTable/buildEntityTableMeta an die Table-Definition hängt.
+// buildEntityTable/deriveEntityTableMeta an die Table-Definition hängt.
 
 import { extractTableName } from "../db";
 import type { Registry } from "../engine/types/feature";

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

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { z } from "zod";
+import type { SseBroker } from "../../api/sse-broker";
 import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
 import type { TenantId } from "../../engine/types/identifiers";
 import { createSecret } from "../../secrets/types";
@@ -292,6 +293,66 @@ describe("dispatcher.stream", () => {
     ).rejects.toMatchObject({ code: "access_denied" });
   });
 
+  test("access invalidation mid-stream rejects with AccessDeniedError and unsubscribes", async () => {
+    let onInvalidate: (() => void) | undefined;
+    let unsubscribeCalls = 0;
+    const broker: SseBroker = {
+      addClient() {
+        return "c";
+      },
+      removeClient() {},
+      pushToChannel() {},
+      getClientCount() {
+        return 0;
+      },
+      getTotalClientCount() {
+        return 0;
+      },
+      subscribeAccessInvalidation(_userId, cb) {
+        onInvalidate = cb;
+        return () => {
+          unsubscribeCalls++;
+        };
+      },
+      publishAccessInvalidation() {},
+    };
+
+    let releaseHang: (() => void) | undefined;
+    const hang = new Promise<void>((resolve) => {
+      releaseHang = resolve;
+    });
+
+    const revokeFeature = defineFeature("revoke", (r) => {
+      r.streamHandler(
+        "tail",
+        z.object({}),
+        async function* () {
+          yield { i: 0 };
+          await hang;
+          yield { i: 1 };
+          releaseHang?.();
+        },
+        { access: { roles: ["Admin"] } },
+      );
+    });
+
+    const user = createTestUser({ roles: ["Admin"] });
+    const dispatcher = createDispatcher(createRegistry([revokeFeature]), {}, { sseBroker: broker });
+    const gen = dispatcher.stream("revoke:stream:tail", {}, user);
+    const first = await gen.next();
+    expect(first.value).toEqual({ i: 0 });
+    expect(onInvalidate).toBeDefined();
+    // Start the idle second pull, then revoke — mirrors heartbeat-only SSE
+    // streams that must die without waiting for the next chunk (#1563).
+    const second = gen.next();
+    onInvalidate?.();
+    await expect(second).rejects.toMatchObject({
+      code: "access_denied",
+      message: expect.stringContaining("access revoked mid-stream"),
+    });
+    expect(unsubscribeCalls).toBe(1);
+  });
+
   test("throws for unknown stream handler", async () => {
     const dispatcher = createTestDispatcher();
 

package/src/pipeline/dispatch-stream.ts

@@ -53,10 +53,8 @@ async function* executeStreamInner(
     throw validationErrorFromZod(parsed.error);
   }
 
-  // Mid-stream access revocation must also cut *idle* SSE streams (heartbeat
-  // only — no chunk). A boolean flag read only after the next chunk would
-  // leave revoked sessions open indefinitely (fw#1563). Race each pull
-  // against an invalidated Deferred instead.
+  // Idle (heartbeat-only) streams must also cut on access revoke — race each
+  // pull against an invalidated Deferred instead of a post-chunk boolean.
   let resolveInvalidated: (() => void) | undefined;
   const invalidated = new Promise<void>((resolve) => {
     resolveInvalidated = resolve;
@@ -66,6 +64,11 @@ async function* executeStreamInner(
   });
 
   let iterator: AsyncIterator<unknown> | undefined;
+  // When access is revoked mid-pull, `iterator.next()` is still in flight.
+  // Awaiting `iterator.return()` in that state deadlocks async generators in
+  // Bun (overlapping next+return). Track abandonment so finally skips the
+  // await; close is fire-and-forget instead (#1563).
+  let abandonedForInvalidation = false;
   try {
     const handlerContext = buildHandlerContext(ctx, type, user);
     const chunks = handler.handler({ type, payload: parsed.data, user }, handlerContext);
@@ -78,6 +81,9 @@ async function* executeStreamInner(
         invalidated.then(() => ({ kind: "invalidated" as const })),
       ]);
       if (outcome.kind === "invalidated") {
+        abandonedForInvalidation = true;
+        void nextPull.catch(() => {});
+        void iterator.return?.(undefined)?.then(undefined, () => {});
         throw new AccessDeniedError({
           message: `access revoked mid-stream for ${type}`,
           details: { handler: type },
@@ -90,11 +96,12 @@ async function* executeStreamInner(
     }
   } finally {
     unsubscribeAccessInvalidation?.();
-    // Consumer break / access revoke / throw — always close the handler
-    // generator so its finally (cleanup) runs (for-await would do this).
-    // Do NOT swallow return() errors — close-time cleanup failures must
-    // surface to runStreamInstrumented (#1543).
-    if (iterator !== undefined) {
+    // Consumer break / throw — always close the handler generator so its
+    // finally (cleanup) runs (for-await would do this). Do NOT swallow
+    // return() errors — close-time cleanup failures must surface to
+    // runStreamInstrumented (#1543). Skip the await after access-revoke
+    // abandonment (overlapping next+return deadlocks — see above).
+    if (iterator !== undefined && !abandonedForInvalidation) {
       await iterator.return?.(undefined);
     }
   }