@cosmicdrift/kumiko-framework 0.156.2 → 0.157.0

package/src/engine/__tests__/{raw-table.test.ts → store-table.test.ts}

@@ -1,9 +1,9 @@
-// Unit tests for r.rawTable() — declaration-time validation + registry
-// aggregation. Post-drizzle-cut merge of the former r.rawTable() (legacy
+// Unit tests for r.storeTable() — declaration-time validation + registry
+// aggregation. Post-drizzle-cut merge of the former r.storeTable() (legacy
 // Drizzle PgTable) and r.unmanagedTable() (EntityTableMeta) — this file
 // absorbs the former unmanaged-table.test.ts coverage under the new name.
 // Full DB roundtrip (setupTestStack pushes the table → INSERT / SELECT)
-// lives in src/__tests__/raw-table.integration.test.ts.
+// lives in src/__tests__/store-table.integration.test.ts.
 
 import { describe, expect, test } from "bun:test";
 import {
@@ -24,7 +24,7 @@ const probeMetaTwo = defineUnmanagedTable({
   columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
 });
 
-describe("r.rawTable — declaration", () => {
+describe("r.storeTable — declaration", () => {
   test("rejects an invalid table name", () => {
     const badMeta = defineUnmanagedTable({
       tableName: "BadName",
@@ -32,7 +32,7 @@ describe("r.rawTable — declaration", () => {
     });
     expect(() =>
       defineFeature("probe", (r) => {
-        r.rawTable(badMeta, { reason: "test" });
+        r.storeTable(badMeta, { reason: "test" });
       }),
     ).toThrow(/must be a valid identifier/);
   });
@@ -40,8 +40,8 @@ describe("r.rawTable — declaration", () => {
   test("rejects duplicate registrations within one feature", () => {
     expect(() =>
       defineFeature("probe", (r) => {
-        r.rawTable(probeMeta, { reason: "test" });
-        r.rawTable(probeMeta, { reason: "test" });
+        r.storeTable(probeMeta, { reason: "test" });
+        r.storeTable(probeMeta, { reason: "test" });
       }),
     ).toThrow(/already registered/);
   });
@@ -49,7 +49,7 @@ describe("r.rawTable — declaration", () => {
   test("rejects empty reason", () => {
     expect(() =>
       defineFeature("probe", (r) => {
-        r.rawTable(probeMeta, { reason: "" });
+        r.storeTable(probeMeta, { reason: "" });
       }),
     ).toThrow(/options\.reason must be a non-empty string/);
   });
@@ -57,49 +57,62 @@ describe("r.rawTable — declaration", () => {
   test("rejects whitespace-only reason", () => {
     expect(() =>
       defineFeature("probe", (r) => {
-        r.rawTable(probeMeta, { reason: "   " });
+        r.storeTable(probeMeta, { reason: "   " });
       }),
     ).toThrow(/options\.reason must be a non-empty string/);
   });
 
+  test("rejects an EntityTableMeta whose source is not 'unmanaged' (#1209)", () => {
+    const managedEntity = createEntity({
+      table: "rt_probe_managed",
+      fields: { name: createTextField() },
+    });
+    const managedMeta = buildEntityTableMeta("rt-probe-managed", managedEntity);
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.storeTable(managedMeta, { reason: "test" });
+      }),
+    ).toThrow(/requires source: "unmanaged"/);
+  });
+
   test("accepts valid registration and stores meta + reason", () => {
     const feature = defineFeature("probe", (r) => {
-      r.rawTable(probeMeta, {
+      r.storeTable(probeMeta, {
         reason: "read-side projection of an event-stream",
       });
     });
-    expect(feature.rawTables).toHaveProperty("rt_probe");
-    expect(feature.rawTables["rt_probe"]?.reason).toBe("read-side projection of an event-stream");
-    expect(feature.rawTables["rt_probe"]?.meta).toBe(probeMeta);
+    expect(feature.storeTables).toHaveProperty("rt_probe");
+    expect(feature.storeTables["rt_probe"]?.reason).toBe("read-side projection of an event-stream");
+    expect(feature.storeTables["rt_probe"]?.meta).toBe(probeMeta);
   });
 
-  test("two raw tables on one feature register under their tableName", () => {
+  test("two store tables on one feature register under their tableName", () => {
     const feature = defineFeature("dual", (r) => {
-      r.rawTable(probeMeta, { reason: "one" });
-      r.rawTable(probeMetaTwo, { reason: "two" });
+      r.storeTable(probeMeta, { reason: "one" });
+      r.storeTable(probeMetaTwo, { reason: "two" });
     });
-    expect(Object.keys(feature.rawTables).sort()).toEqual(["rt_probe", "rt_probe_two"]);
+    expect(Object.keys(feature.storeTables).sort()).toEqual(["rt_probe", "rt_probe_two"]);
   });
 
-  test("absent rawTables on a feature is ok", () => {
+  test("absent storeTables on a feature is ok", () => {
     const feat = defineFeature("plain", () => {
-      // no r.rawTable calls
+      // no r.storeTable calls
     });
-    expect(feat.rawTables).toEqual({});
+    expect(feat.storeTables).toEqual({});
   });
 });
 
-describe("createRegistry — rawTable aggregation", () => {
-  test("aggregates raw tables across features and tags featureName", () => {
+describe("createRegistry — storeTable aggregation", () => {
+  test("aggregates store tables across features and tags featureName", () => {
     const featA = defineFeature("billing", (r) => {
-      r.rawTable(probeMeta, { reason: "external API cache" });
+      r.storeTable(probeMeta, { reason: "external API cache" });
     });
     const featB = defineFeature("inventory", (r) => {
-      r.rawTable(probeMetaTwo, { reason: "imported pre-ES" });
+      r.storeTable(probeMetaTwo, { reason: "imported pre-ES" });
     });
 
     const registry = createRegistry([featA, featB]);
-    const all = registry.getAllRawTables();
+    const all = registry.getAllStoreTables();
 
     expect(all.size).toBe(2);
     expect(all.get("rt_probe")?.featureName).toBe("billing");
@@ -111,10 +124,10 @@ describe("createRegistry — rawTable aggregation", () => {
     // Two features can't share the same physical tableName — migrate-runner
     // would race two CREATE TABLE statements. Boot-validator catches it.
     const featA = defineFeature("a", (r) => {
-      r.rawTable(probeMeta, { reason: "first" });
+      r.storeTable(probeMeta, { reason: "first" });
     });
     const featB = defineFeature("b", (r) => {
-      r.rawTable(probeMeta, { reason: "second" });
+      r.storeTable(probeMeta, { reason: "second" });
     });
     expect(() => createRegistry([featA, featB])).toThrow(
       /Raw-table "rt_probe" registered by both feature "a" and "b"/,
@@ -123,16 +136,20 @@ describe("createRegistry — rawTable aggregation", () => {
 
   test("two features with distinct tableNames register cleanly", () => {
     const featA = defineFeature("a", (r) => {
-      r.rawTable(probeMeta, { reason: "first" });
+      r.storeTable(probeMeta, { reason: "first" });
     });
     const featB = defineFeature("b", (r) => {
-      r.rawTable(probeMetaTwo, { reason: "second" });
+      r.storeTable(probeMetaTwo, { reason: "second" });
     });
     expect(() => createRegistry([featA, featB])).not.toThrow();
   });
 
-  test("rejects a raw-table that collides with an entity's physical name", () => {
-    const widget = createEntity({ fields: { name: createTextField() } });
+  test("rejects a store-table that collides with an entity's physical name", () => {
+    // Custom `table` override without the read_ prefix — resolveTableName's
+    // default would carry read_, which r.storeTable now rejects outright
+    // (#1220), so the collision case needs a table name storeTable can
+    // actually register.
+    const widget = createEntity({ table: "shop_widgets", fields: { name: createTextField() } });
     // resolveTableName mirrors the migrate-runner — pin the exact physical name.
     const physical = resolveTableName("widget", widget, "shop");
     const clashing = defineUnmanagedTable({
@@ -143,22 +160,22 @@ describe("createRegistry — rawTable aggregation", () => {
       r.entity("widget", widget);
     });
     const tableFeature = defineFeature("other", (r) => {
-      r.rawTable(clashing, { reason: "clash" });
+      r.storeTable(clashing, { reason: "clash" });
     });
 
-    // Entity registered first, then the colliding raw table.
+    // Entity registered first, then the colliding store table.
     expect(() => createRegistry([entityFeature, tableFeature])).toThrow(
       new RegExp(`Raw-table "${physical}".*collides with the physical table of entity "widget"`),
     );
 
-    // Order-independent: raw table registered first, then the entity.
+    // Order-independent: store table registered first, then the entity.
     expect(() => createRegistry([tableFeature, entityFeature])).toThrow(
-      new RegExp(`Entity "widget".*collides with r.rawTable\\("${physical}"\\)`),
+      new RegExp(`Entity "widget".*collides with r.storeTable\\("${physical}"\\)`),
     );
   });
 });
 
-describe("createRegistry — raw tables with PII-annotated fields (#820)", () => {
+describe("createRegistry — store tables with PII-annotated fields (#820)", () => {
   const piiEntity = createEntity({
     table: "rt_pii_probe",
     fields: {
@@ -166,15 +183,15 @@ describe("createRegistry — raw tables with PII-annotated fields (#820)", () =>
       ip: createTextField({ userOwned: { ownerField: "userId" } }),
     },
   });
-  const piiMeta = buildEntityTableMeta("rt-pii-probe", piiEntity);
+  const piiMeta = buildEntityTableMeta("rt-pii-probe", piiEntity, { source: "unmanaged" });
 
   test("buildEntityTableMeta records the subject-annotated field names", () => {
     expect(piiMeta.piiSubjectFields).toEqual(["ip"]);
   });
 
-  test("rejects a PII-carrying raw table without piiEncryptedOnWrite", () => {
+  test("rejects a PII-carrying store table without piiEncryptedOnWrite", () => {
     const feat = defineFeature("probe", (r) => {
-      r.rawTable(piiMeta, { reason: "direct-write store" });
+      r.storeTable(piiMeta, { reason: "direct-write store" });
     });
     expect(() => createRegistry([feat])).toThrow(
       /has PII-annotated fields \(ip\) but direct writes bypass the executor's PII encryption/,
@@ -183,7 +200,7 @@ describe("createRegistry — raw tables with PII-annotated fields (#820)", () =>
 
   test("accepts it once the feature declares piiEncryptedOnWrite", () => {
     const feat = defineFeature("probe", (r) => {
-      r.rawTable(piiMeta, {
+      r.storeTable(piiMeta, {
         reason: "direct-write store",
         piiEncryptedOnWrite: true,
       });
@@ -191,9 +208,9 @@ describe("createRegistry — raw tables with PII-annotated fields (#820)", () =>
     expect(() => createRegistry([feat])).not.toThrow();
   });
 
-  test("a PII-free raw table needs no declaration", () => {
+  test("a PII-free store table needs no declaration", () => {
     const feat = defineFeature("probe", (r) => {
-      r.rawTable(probeMeta, { reason: "plain store" });
+      r.storeTable(probeMeta, { reason: "plain store" });
     });
     expect(() => createRegistry([feat])).not.toThrow();
   });

package/src/engine/boot-validator/action-wiring.ts

@@ -1,4 +1,11 @@
-import type { EditFieldSpec, FeatureDefinition, RowAction, ToolbarAction } from "../types";
+import type {
+  EditFieldSpec,
+  EditLayout,
+  FeatureDefinition,
+  ListColumnSpec,
+  RowAction,
+  ToolbarAction,
+} from "../types";
 import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../types/screen";
 
 const FUNCTION_DROPPED_HINT =
@@ -55,6 +62,7 @@ const EDIT_FIELD_FUNCTION_FIELDS = ["visible", "readOnly", "required"] as const;
 function validateEditFieldNoFunctions(
   featureName: string,
   screenId: string,
+  screenType: string,
   fieldSpec: EditFieldSpec,
 ): void {
   const normalized = normalizeEditField(fieldSpec);
@@ -62,37 +70,79 @@ function validateEditFieldNoFunctions(
   for (const key of EDIT_FIELD_FUNCTION_FIELDS) {
     throwIfFunction(
       record[key],
-      `[Feature ${featureName}] Screen "${screenId}" (entityEdit) field "${normalized.field}" ` +
+      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${normalized.field}" ` +
         `${key} is a function — ${FUNCTION_DROPPED_HINT} Use a FieldCondition ` +
         `(boolean or { field, eq }/{ field, ne }) instead.`,
     );
   }
   throwIfFunction(
     normalized.renderer,
-    `[Feature ${featureName}] Screen "${screenId}" (entityEdit) field "${normalized.field}" ` +
+    `[Feature ${featureName}] Screen "${screenId}" (${screenType}) field "${normalized.field}" ` +
       `renderer is a function — ${FUNCTION_DROPPED_HINT} Use a FormatSpec ({ format: "..." }) instead.`,
   );
 }
 
+function validateColumnsNoFunctions(
+  featureName: string,
+  screenId: string,
+  screenType: string,
+  columns: readonly ListColumnSpec[],
+): void {
+  for (const col of columns) {
+    const normalized = normalizeListColumn(col);
+    throwIfFunction(
+      normalized.renderer,
+      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) column ` +
+        `"${normalized.field}" renderer is a function — ${FUNCTION_DROPPED_HINT} ` +
+        `Use a FormatSpec ({ format: "..." }) instead.`,
+    );
+  }
+}
+
+function validateEditLayoutNoFunctions(
+  featureName: string,
+  screenId: string,
+  screenType: string,
+  layout: EditLayout,
+): void {
+  for (const section of layout.sections) {
+    if (isExtensionEditSection(section)) continue;
+    for (const fieldSpec of section.fields) {
+      validateEditFieldNoFunctions(featureName, screenId, screenType, fieldSpec);
+    }
+  }
+}
+
+// Screen types that carry an EditLayout (entityEdit's layout shape, reused
+// verbatim by actionForm/configEdit/projectionDetail) vs. ones that carry
+// ListColumnSpec[] (entityList/projectionList, plus dashboard "list" panels)
+// both funnel through the same two checks below — a function literal in
+// either shape is dropped by JSON.stringify regardless of which screen type
+// hosts it.
 export function validateFieldWiring(feature: FeatureDefinition): void {
   for (const screen of Object.values(feature.screens)) {
     if (screen.type === "entityList" || screen.type === "projectionList") {
-      for (const col of screen.columns) {
-        const normalized = normalizeListColumn(col);
-        throwIfFunction(
-          normalized.renderer,
-          `[Feature ${feature.name}] Screen "${screen.id}" (${screen.type}) column ` +
-            `"${normalized.field}" renderer is a function — ${FUNCTION_DROPPED_HINT} ` +
-            `Use a FormatSpec ({ format: "..." }) instead.`,
-        );
-      }
+      validateColumnsNoFunctions(feature.name, screen.id, screen.type, screen.columns);
       continue;
     }
-    if (screen.type !== "entityEdit") continue;
-    for (const section of screen.layout.sections) {
-      if (isExtensionEditSection(section)) continue;
-      for (const fieldSpec of section.fields) {
-        validateEditFieldNoFunctions(feature.name, screen.id, fieldSpec);
+    if (
+      screen.type === "entityEdit" ||
+      screen.type === "actionForm" ||
+      screen.type === "configEdit" ||
+      screen.type === "projectionDetail"
+    ) {
+      validateEditLayoutNoFunctions(feature.name, screen.id, screen.type, screen.layout);
+      continue;
+    }
+    if (screen.type === "dashboard") {
+      for (const panel of screen.panels) {
+        if (panel.kind !== "list") continue;
+        validateColumnsNoFunctions(
+          feature.name,
+          `${screen.id}:${panel.id}`,
+          "dashboard-list",
+          panel.columns,
+        );
       }
     }
   }

package/src/engine/define-feature.ts

@@ -152,7 +152,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     navs: state.navs,
     workspaces: state.workspaces,
     httpRoutes: state.httpRoutes,
-    rawTables: state.rawTables,
+    storeTables: state.storeTables,
     ...(state.treeActions !== undefined && { treeActions: state.treeActions }),
     ...(state.envSchema !== undefined && { envSchema: state.envSchema }),
   };

package/src/engine/feature-ast/__tests__/parse-real-features.test.ts

@@ -69,7 +69,7 @@ const FEATURES: readonly RealFeature[] = [
     path: "packages/bundled-features/src/sessions/feature.ts",
     expectedFeatureName: "sessions",
     recognisedKinds: ["hook", "writeHandler", "queryHandler"],
-    errorMethodNames: ["rawTable", "job"],
+    errorMethodNames: ["storeTable", "job"],
   },
   {
     path: "packages/bundled-features/src/auth-email-password/feature.ts",

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

@@ -60,7 +60,7 @@ export {
   extractEnvSchema,
   extractExposesApi,
   extractExtendsRegistrar,
-  extractRawTable,
+  extractStoreTable,
   extractUsesApi,
 } from "./round5";
 export { extractTreeActions } from "./round6";

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

@@ -95,7 +95,7 @@ export function extractExposesApi(
   });
 }
 
-export function extractRawTable(
+export function extractStoreTable(
   call: CallExpression,
   sourceFile: SourceFile,
 ): ExtractOutput<never> {
@@ -104,8 +104,8 @@ export function extractRawTable(
   // so there is nothing to extract statically. A clean ParseError (not
   // UnknownPattern) marks it design-time-unreadable, like entity-by-identifier.
   return fail(
-    "rawTable",
+    "storeTable",
     sourceLocationFromNode(call, sourceFile),
-    "rawTable meta is a factory/identifier argument, not a static literal",
+    "storeTable meta is a factory/identifier argument, not a static literal",
   );
 }

package/src/engine/feature-ast/parse.ts

@@ -51,13 +51,13 @@ import {
   extractOptionalRequires,
   extractProjection,
   extractQueryHandler,
-  extractRawTable,
   extractReadsConfig,
   extractReferenceData,
   extractRelation,
   extractRequires,
   extractScreen,
   extractSecret,
+  extractStoreTable,
   extractSystemScope,
   extractToggleable,
   extractTranslations,
@@ -468,8 +468,8 @@ function dispatchExtractor(
       return extractUsesApi(call, sourceFile);
     case "exposesApi":
       return extractExposesApi(call, sourceFile);
-    case "rawTable":
-      return extractRawTable(call, sourceFile);
+    case "storeTable":
+      return extractStoreTable(call, sourceFile);
     // Round 6 — Tree-Actions pattern
     case "treeActions":
       return extractTreeActions(call, sourceFile);

package/src/engine/feature-builder-state.ts

@@ -22,13 +22,13 @@ import type {
   PreDeleteHookFn,
   ProjectionDefinition,
   QueryHandlerDef,
-  RawTableEntry,
   ReferenceDataDef,
   RegistrarExtensionDef,
   RegistrarExtensionRegistration,
   RelationDefinition,
   SearchPayloadContributorFn,
   SecretKeyDefinition,
+  StoreTableEntry,
   TranslationKeys,
   TreeActionDef,
   UiHints,
@@ -86,7 +86,7 @@ export type FeatureBuilderState = {
   projections: Record<string, ProjectionDefinition>;
   multiStreamProjections: Record<string, MultiStreamProjectionDefinition>;
   entityProjectionExtensions: Record<string, EntityProjectionExtension[]>;
-  rawTables: Record<string, RawTableEntry>;
+  storeTables: Record<string, StoreTableEntry>;
   authClaimsHooks: AuthClaimsFn[];
   claimKeys: Record<string, ClaimKeyDefinition>;
   screens: Record<string, ScreenDefinition>;
@@ -144,7 +144,7 @@ export function createInitialFeatureBuilderState(): FeatureBuilderState {
     projections: {},
     multiStreamProjections: {},
     entityProjectionExtensions: {},
-    rawTables: {},
+    storeTables: {},
     authClaimsHooks: [],
     claimKeys: {},
     screens: {},

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

@@ -14,9 +14,9 @@ import type {
   PostSaveHookFn,
   PreDeleteHookFn,
   ProjectionDefinition,
-  RawTableOptions,
   RegistrarExtensionDef,
   SearchPayloadContributorFn,
+  StoreTableOptions,
   TreeActionDef,
   TreeActionsHandle,
   ValidationHookFn,
@@ -89,6 +89,28 @@ export function buildUiExtensionsMethods<TName extends string>(
   state: FeatureBuilderState,
   name: TName,
 ) {
+  // Shared by r.nav() and r.screen()'s inline nav-sugar path — one place
+  // for id-validation + collision checks so future registration-time
+  // checks (e.g. parent-format, reserved ids) apply to both call sites
+  // instead of only the standalone r.nav() one.
+  function registerNav(navDefinition: NavDefinition): void {
+    if (!isKebabSegment(navDefinition.id)) {
+      throw new Error(
+        `[Feature ${name}] Nav id "${navDefinition.id}" must be kebab-case ` +
+          `(lowercase letters, digits, dashes; start with a letter). ` +
+          `Got "${navDefinition.id}" — try "${toKebab(navDefinition.id).replace(/_/g, "-")}".`,
+      );
+    }
+    if (state.navs[navDefinition.id]) {
+      throw new Error(
+        `[Feature ${name}] Nav entry "${navDefinition.id}" already registered. ` +
+          `Nav ids must be unique per feature — remove the standalone ` +
+          `r.nav("${navDefinition.id}", ...) call or the screen's inline nav.`,
+      );
+    }
+    state.navs[navDefinition.id] = navDefinition;
+  }
+
   return {
     hook(
       type: LifecycleHookType | "validation",
@@ -334,42 +356,18 @@ export function buildUiExtensionsMethods<TName extends string>(
         // Sugar for the common "one nav entry pointing at this screen"
         // case — synthesizes id/screen from the screen's own id. Beyond
         // label/icon/parent/order, declare a standalone r.nav() instead.
-        if (state.navs[definition.id]) {
-          throw new Error(
-            `[Feature ${name}] Nav entry "${definition.id}" already registered. ` +
-              `Nav ids must be unique per feature — remove the standalone ` +
-              `r.nav("${definition.id}", ...) call or the screen's inline nav.`,
-          );
-        }
-        const navDefinition: NavDefinition = {
+        registerNav({
           id: definition.id,
           label: definition.nav.label,
           icon: definition.nav.icon,
           parent: definition.nav.parent,
           order: definition.nav.order,
           screen: `${name}:screen:${definition.id}`,
-        };
-        state.navs[definition.id] = navDefinition;
+        });
       }
     },
     nav(definition: NavDefinition): void {
-      // Reject kebab-drift at registration-time so the stack trace points at
-      // the feature file, not at registry-boot. Same guard pattern as
-      // r.projection / r.multiStreamProjection / r.screen.
-      if (!isKebabSegment(definition.id)) {
-        throw new Error(
-          `[Feature ${name}] Nav id "${definition.id}" must be kebab-case ` +
-            `(lowercase letters, digits, dashes; start with a letter). ` +
-            `Got "${definition.id}" — try "${toKebab(definition.id).replace(/_/g, "-")}".`,
-        );
-      }
-      if (state.navs[definition.id]) {
-        throw new Error(
-          `[Feature ${name}] Nav entry "${definition.id}" already registered. ` +
-            `Nav ids must be unique per feature.`,
-        );
-      }
-      state.navs[definition.id] = definition;
+      registerNav(definition);
     },
     workspace(definition: WorkspaceDefinition): void {
       // Same kebab guard as r.screen / r.nav so authoring-time mistakes
@@ -416,7 +414,7 @@ export function buildUiExtensionsMethods<TName extends string>(
       }
       state.httpRoutes[key] = definition;
     },
-    rawTable(meta: EntityTableMeta, options: RawTableOptions): void {
+    storeTable(meta: EntityTableMeta, options: StoreTableOptions): void {
       // Name comes from the meta itself — apps already give the table a
       // name when calling defineUnmanagedTable, no need to repeat it.
       const tableName = meta.tableName;
@@ -428,23 +426,46 @@ export function buildUiExtensionsMethods<TName extends string>(
             `valid identifier (lowercase letters, digits, underscores; start with a letter).`,
         );
       }
-      if (state.rawTables[tableName]) {
+      if (state.storeTables[tableName]) {
         throw new Error(
-          `[Feature ${name}] r.rawTable("${tableName}") already registered. ` +
+          `[Feature ${name}] r.storeTable("${tableName}") already registered. ` +
             `Raw-table names must be unique per feature.`,
         );
       }
+      // `read_` is reserved for r.entity()/r.projection() (managed,
+      // event-sourced, rebuildable). storeTable is the unmanaged
+      // direct-write escape hatch — the prefix must say so (#1220).
+      if (tableName.startsWith("read_")) {
+        throw new Error(
+          `[Feature ${name}] r.storeTable("${tableName}"): the "read_" prefix is reserved ` +
+            `for managed r.entity()/r.projection() tables. Pick an unprefixed name or a ` +
+            `distinct prefix (e.g. "store_${tableName.slice("read_".length)}").`,
+        );
+      }
+      // meta.source must agree with the r.storeTable() escape hatch, or the
+      // migrate-generator treats schema drift on this table as safe to
+      // DROP+rebuild-from-events — wiping direct-write data with no events
+      // to replay it from (#1209).
+      if (meta.source !== "unmanaged") {
+        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" })) — ` +
+            `otherwise the migration generator will treat schema drift on this table as safe ` +
+            `to DROP+rebuild, wiping any direct-write data.`,
+        );
+      }
       // The `reason` is the marker that justifies the bypass — empty
       // strings would defeat the audit trail. Reject early so the
       // failure points at the feature file.
       if (typeof options.reason !== "string" || options.reason.trim().length === 0) {
         throw new Error(
-          `[Feature ${name}] r.rawTable("${tableName}"): options.reason must be a ` +
+          `[Feature ${name}] r.storeTable("${tableName}"): options.reason must be a ` +
             `non-empty string. The reason justifies the audit-trail bypass — ` +
             `if you can't write one, declare data via r.entity() instead.`,
         );
       }
-      state.rawTables[tableName] = {
+      state.storeTables[tableName] = {
         name: tableName,
         meta,
         reason: options.reason,

package/src/engine/registry-facade.ts

@@ -22,7 +22,6 @@ import type {
   PreSaveHookFn,
   ProjectionDefinition,
   QueryHandlerDef,
-  RawTableDef,
   ReferenceDataDef,
   RegistrarExtensionDef,
   RegistrarExtensionRegistration,
@@ -30,6 +29,7 @@ import type {
   ScreenDefinition,
   SearchPayloadContributorFn,
   SecretKeyDefinition,
+  StoreTableDef,
   TranslationKeys,
   TreeActionDef,
   WorkspaceDefinition,
@@ -266,8 +266,8 @@ export function buildRegistryFacade(state: RegistryState): Registry {
       return state.projectionMap;
     },
 
-    getAllRawTables(): ReadonlyMap<string, RawTableDef> {
-      return state.rawTableMap;
+    getAllStoreTables(): ReadonlyMap<string, StoreTableDef> {
+      return state.storeTableMap;
     },
 
     getAllMultiStreamProjections(): ReadonlyMap<string, MultiStreamProjectionDefinition> {