@cosmicdrift/kumiko-framework 0.156.3 → 0.157.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.156.3",
+  "version": "0.157.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -193,7 +193,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.156.3",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.157.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -1,5 +1,5 @@
-// Integration test for r.rawTable() — proves the full boot path:
-// defineFeature declares a raw table → setupTestStack auto-pushes it →
+// Integration test for r.storeTable() — proves the full boot path:
+// defineFeature declares a store table → setupTestStack auto-pushes it →
 // INSERT/SELECT against the real DB roundtrip. Plan reference:
 // kumiko-platform/docs/plans/architecture/table-ddl-guard.md (Stufe 3).
 
@@ -9,7 +9,7 @@ import { asRawClient, insertOne, selectMany } from "../db/query";
 import { defineFeature } from "../engine";
 import { setupTestStack, type TestStack, unsafePushTables } from "../stack";
 
-// External-system payload cache — the textbook r.rawTable() use case:
+// External-system payload cache — the textbook r.storeTable() use case:
 // write-only by an integration handler, read-only by a query, never
 // event-sourced (the data isn't a domain fact, it's a side-effect
 // snapshot).
@@ -23,7 +23,7 @@ const stripeWebhookCacheMeta = defineUnmanagedTable({
 });
 
 const webhookCacheFeature = defineFeature("webhook-cache", (r) => {
-  r.rawTable(stripeWebhookCacheMeta, {
+  r.storeTable(stripeWebhookCacheMeta, {
     reason: "external Stripe webhook payload cache — write-only by webhook handler",
   });
 });
@@ -38,7 +38,7 @@ afterAll(async () => {
   await stack.cleanup();
 });
 
-describe("r.rawTable — DB roundtrip via setupTestStack", () => {
+describe("r.storeTable — DB roundtrip via setupTestStack", () => {
   test("table is auto-pushed and accepts INSERT + SELECT", async () => {
     const eventId = "evt_test_123";
     const payload = JSON.stringify({ type: "invoice.paid", amount: 4200 });
@@ -52,8 +52,8 @@ describe("r.rawTable — DB roundtrip via setupTestStack", () => {
     expect(rows[0]?.receivedAt).toBeInstanceOf(Temporal.Instant);
   });
 
-  test("registry exposes the raw table with its reason and featureName", () => {
-    const all = stack.registry.getAllRawTables();
+  test("registry exposes the store table with its reason and featureName", () => {
+    const all = stack.registry.getAllStoreTables();
     const entry = all.get("rt_int_stripe_webhook_cache");
     expect(entry).toBeDefined();
     expect(entry?.featureName).toBe("webhook-cache");
@@ -62,9 +62,9 @@ describe("r.rawTable — DB roundtrip via setupTestStack", () => {
   });
 
   test("INSERT bypasses the event store — no kumiko_events row produced", async () => {
-    // Proves that the rawTable lives outside the event-sourcing graph:
+    // Proves that the storeTable lives outside the event-sourcing graph:
     // a write to it shouldn't append anything to kumiko_events. If a
-    // future regression accidentally routed raw-table writes through
+    // future regression accidentally routed store-table writes through
     // the executor, a row would show up here.
     const before = await asRawClient(stack.db).unsafe<{ count: string }>(
       `SELECT COUNT(*)::text AS count FROM kumiko_events`,
@@ -84,7 +84,7 @@ describe("r.rawTable — DB roundtrip via setupTestStack", () => {
     expect(afterCount).toBe(beforeCount);
   });
 
-  test("a second push on the same rawTable is idempotent — CREATE IF NOT EXISTS", async () => {
+  test("a second push on the same storeTable is idempotent — CREATE IF NOT EXISTS", async () => {
     // unsafePushTables uses CREATE TABLE IF NOT EXISTS — idempotent by design.
     await expect(
       unsafePushTables(stack.db, { idem: stripeWebhookCacheMeta }),

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

@@ -15,6 +15,7 @@ import {
   type SaveContext,
 } from "../../engine";
 import { UnprocessableError, writeFailure } from "../../errors";
+import { RedisKeys } from "../../pipeline/redis-keys";
 import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
 
 // Entity: a simple "item" with name + counter
@@ -370,6 +371,73 @@ describe("POST /api/batch", () => {
     expect(inTxHookLog).toHaveLength(1);
     expect(afterCommitHookLog).toHaveLength(1);
   });
+
+  test("idempotency: failed batch is cached — retry returns same error without re-exec", async () => {
+    const requestId = "batch-rid-fail-cache";
+    const commands = [
+      { type: "batch:write:item:create", payload: { name: "should-rollback" } },
+      { type: "batch:write:item:fail", payload: { name: "stop" } },
+    ];
+
+    const first = await stack.http.batch(commands, admin, requestId);
+    const firstBody = await first.json();
+    expect(first.status).toBe(422);
+    expect(firstBody.isSuccess).toBe(false);
+    expect(firstBody.failedIndex).toBe(1);
+    expect(inTxHookLog.map((h) => h.name)).toEqual(["should-rollback"]);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(0);
+
+    inTxHookLog.length = 0;
+    afterCommitHookLog.length = 0;
+
+    const second = await stack.http.batch(commands, admin, requestId);
+    const secondBody = await second.json();
+    expect(second.status).toBe(422);
+    expect(secondBody.isSuccess).toBe(false);
+    expect(secondBody.failedIndex).toBe(firstBody.failedIndex);
+    // HTTP re-serializes the cached failure with a fresh requestId/timestamp —
+    // pin the stable business fields, not the transport envelope.
+    expect(secondBody.error.code).toBe(firstBody.error.code);
+    expect(secondBody.error.details).toEqual(firstBody.error.details);
+    // Cached path must not re-run commands (hooks stay empty, DB empty)
+    expect(inTxHookLog).toHaveLength(0);
+    expect(afterCommitHookLog).toHaveLength(0);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(0);
+  });
+
+  test("idempotency: corrupted cache entry is treated as miss and re-runs", async () => {
+    const requestId = "batch-rid-corrupt";
+    await stack.redis.redis.set(`${RedisKeys.idempotency}${requestId}`, "{not-json", "EX", 60);
+
+    const res = await stack.http.batch(
+      [{ type: "batch:write:item:create", payload: { name: "after-corrupt" } }],
+      admin,
+      requestId,
+    );
+    const body = await res.json();
+    expect(res.status).toBe(200);
+    expect(body.isSuccess).toBe(true);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(1);
+    expect(inTxHookLog.map((h) => h.name)).toEqual(["after-corrupt"]);
+  });
+
+  test("mid-batch handler throw: rolls back prior writes, afterCommit does not fire", async () => {
+    const res = await stack.http.batch(
+      [
+        { type: "batch:write:item:create", payload: { name: "before-throw" } },
+        { type: "batch:write:item:throw", payload: { name: "boom" } },
+        { type: "batch:write:item:create", payload: { name: "never" } },
+      ],
+      admin,
+    );
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.failedIndex).toBe(1);
+    expect(inTxHookLog.map((h) => h.name)).toEqual(["before-throw"]);
+    expect(afterCommitHookLog).toEqual([]);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(0);
+    expect(await selectMany(stack.db, auditTable)).toHaveLength(0);
+  });
 });
 
 describe("POST /api/write (single write runs in its own transaction)", () => {

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

@@ -20,7 +20,7 @@ const counterTable = table("read_unit_counters", {
 }) as unknown as SchemaTable;
 
 describe("collectTableMetas (#255)", () => {
-  test("collects entity, projection, MSP and rawTable tables — same sources as the test-stack auto-push", () => {
+  test("collects entity, projection, MSP and storeTable tables — same sources as the test-stack auto-push", () => {
     const feature = defineFeature("test", (r) => {
       r.entity("unit", exampleEntity());
       r.projection({
@@ -39,16 +39,16 @@ describe("collectTableMetas (#255)", () => {
       });
       // side-effect-only MSP — no table, must be skipped without throwing
       r.multiStreamProjection({ name: "unit-notify", apply: { "unit.created": async () => {} } });
-      r.rawTable(
+      r.storeTable(
         defineUnmanagedTable({
           tableName: "unit_cache",
           columns: [{ name: "id", pgType: "uuid", notNull: true, primaryKey: true }],
         }),
         { reason: "test fixture" },
       );
-      r.rawTable(
+      r.storeTable(
         defineUnmanagedTable({
-          tableName: "read_unit_log",
+          tableName: "store_unit_log",
           columns: [{ name: "id", pgType: "serial", notNull: true, primaryKey: true }],
         }),
         { reason: "test fixture" },
@@ -59,8 +59,8 @@ describe("collectTableMetas (#255)", () => {
     expect(names).toContain("read_units"); // entity
     expect(names).toContain("read_unit_counters"); // r.projection
     expect(names).toContain("read_unit_audit"); // r.multiStreamProjection
-    expect(names).toContain("unit_cache"); // r.rawTable
-    expect(names).toContain("read_unit_log"); // r.rawTable (second registration)
+    expect(names).toContain("unit_cache"); // r.storeTable
+    expect(names).toContain("store_unit_log"); // r.storeTable (second registration)
     expect(names).toHaveLength(5);
   });
 

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

@@ -1,5 +1,5 @@
 // #1210: buildEntityTableMeta() hardcoded source: "managed", so unmanaged
-// direct-write stores (read_user_sessions, read_api_tokens, mail sync/seen
+// 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
 // no events, wiping live data. The options.source escape hatch must produce

package/src/db/__tests__/feature-table-sources.test.ts

@@ -1,10 +1,10 @@
-// Regression test for #255-class drift: rawTables must appear in
+// Regression test for #255-class drift: storeTables must appear in
 // enumerateFeatureTableSources so setupTestStack's auto-push and
 // collectTableMetas see the exact same table set. Before this fix,
 // unmanaged tables were only handled by collectTableMetas directly, so any
 // app relying on setupTestStack's ephemeral DB (Playwright/e2e) never got
-// its raw tables created — e.g. the bundled "sessions" feature's
-// read_user_sessions, breaking every login in an ephemeral test stack.
+// its store tables created — e.g. the bundled "sessions" feature's
+// store_user_sessions, breaking every login in an ephemeral test stack.
 
 import { describe, expect, test } from "bun:test";
 import { defineFeature } from "../../engine/define-feature";
@@ -16,10 +16,10 @@ const probeMeta = defineUnmanagedTable({
   columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
 });
 
-describe("enumerateFeatureTableSources — rawTables", () => {
-  test("includes a feature's rawTable as a table source", () => {
+describe("enumerateFeatureTableSources — storeTables", () => {
+  test("includes a feature's storeTable as a table source", () => {
     const feature = defineFeature("probe", (r) => {
-      r.rawTable(probeMeta, { reason: "direct-write store" });
+      r.storeTable(probeMeta, { reason: "direct-write store" });
     });
     const sources = enumerateFeatureTableSources(feature);
     const entry = sources.find((s) => s.origin.includes("ftst_probe"));
@@ -27,7 +27,7 @@ describe("enumerateFeatureTableSources — rawTables", () => {
     expect(entry?.table).toBe(probeMeta);
   });
 
-  test("a feature with no rawTable contributes nothing extra", () => {
+  test("a feature with no storeTable contributes nothing extra", () => {
     const feature = defineFeature("plain", () => {});
     expect(enumerateFeatureTableSources(feature)).toEqual([]);
   });

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

@@ -1,7 +1,7 @@
 // collectTableMetas — kanonische ENTITY_METAS-Quelle für `kumiko schema
 // generate`. Erfasst dieselben Tabellen-Quellen wie der setupTestStack-
-// auto-push (entities, rawTables, projections, multiStreamProjections) —
-// die frühere Template-Variante sammelte nur entities + rawTables, wodurch
+// auto-push (entities, storeTables, projections, multiStreamProjections) —
+// die frühere Template-Variante sammelte nur entities + storeTables, wodurch
 // projection-only-Tabellen (z.B. billing-foundation read_subscriptions) nie
 // in Migrations landeten und der erste Prod-Write crashte (#255).
 
@@ -59,11 +59,11 @@ export function collectTableMetas(
       metas.push(meta);
       byName.set(meta.tableName, { meta, origin: `entity "${name}" (${feature.name})` });
     }
-    for (const entry of Object.values(feature.rawTables)) {
+    for (const entry of Object.values(feature.storeTables)) {
       metas.push(entry.meta);
       byName.set(entry.meta.tableName, {
         meta: entry.meta,
-        origin: `rawTable "${entry.name}" (${feature.name})`,
+        origin: `storeTable "${entry.name}" (${feature.name})`,
       });
     }
   }

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

@@ -95,7 +95,7 @@ export type EntityTableMeta = {
   // discriminator nutzen um Warnungen zu rendern ("X tables are unmanaged").
   readonly source: "managed" | "unmanaged";
   // PII-Subject-annotated field names (pii/userOwned/tenantOwned). Set by
-  // buildEntityTableMeta so the registry can reject r.rawTable stores
+  // buildEntityTableMeta so the registry can reject r.storeTable stores
   // whose direct writes would skip the executor's encryption (#820).
   readonly piiSubjectFields?: readonly string[];
 };
@@ -432,8 +432,8 @@ export function buildEntityTableMeta(
 // jede neue defineUnmanagedTable-Stelle prüfen.
 //
 // Heutige use-cases im framework:
-//   - `read_delivery_attempts` — id kommt aus dem Aggregate-Stream
-//   - `read_job_run_logs` — child-table, serial PK, kein tenant-scope
+//   - `store_delivery_attempts` — id kommt aus dem Aggregate-Stream
+//   - `store_job_run_logs` — child-table, serial PK, kein tenant-scope
 export type UnmanagedTableInput = {
   readonly tableName: string;
   readonly columns: readonly ColumnMeta[];

package/src/db/feature-table-sources.ts

@@ -1,5 +1,5 @@
 // Single enumeration of every table-bearing registration on a feature
-// (r.projection, r.multiStreamProjection with table, r.rawTable).
+// (r.projection, r.multiStreamProjection with table, r.storeTable).
 // Consumed by BOTH the setupTestStack auto-push and collectTableMetas —
 // one list, so test-DB-push and `kumiko schema generate` cannot drift
 // apart again (#255).
@@ -29,8 +29,8 @@ export function enumerateFeatureTableSources(
       origin: `multiStreamProjection "${name}" (${feature.name})`,
     });
   }
-  for (const [name, raw] of Object.entries(feature.rawTables)) {
-    sources.push({ table: raw.meta, origin: `rawTable "${name}" (${feature.name})` });
+  for (const [name, raw] of Object.entries(feature.storeTables)) {
+    sources.push({ table: raw.meta, origin: `storeTable "${name}" (${feature.name})` });
   }
   return sources;
 }

package/src/db/queries/shadow-swap.ts

@@ -207,7 +207,7 @@ export async function assertNoUnreachableLiveRows(
     `projection-rebuild "${projectionName}": ${countLabel} live rows in "${tableName}" have no ` +
       `event in the projection's source streams and cannot be reconstructed by replay — the swap ` +
       `would silently drop them (ids: ${ids.join(", ")}). A handler direct-inserted these rows ` +
-      `without emitting a .created event. Fix: register the table with r.rawTable(meta, ` +
+      `without emitting a .created event. Fix: register the table with r.storeTable(meta, ` +
       `{ reason }) to opt out of rebuild, or emit the missing events. See ` +
       `docs/reference/entity-write-patterns.md. Rebuild aborted; live table untouched.`,
   );

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/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,
@@ -414,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;
@@ -426,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> {

package/src/engine/registry-ingest.ts

@@ -23,7 +23,7 @@ export function populateFeatureCore(state: RegistryState, feature: FeatureDefini
     if (clash?.kind === "raw") {
       throw new Error(
         `Entity "${name}" (feature "${feature.name}") has physical table "${physical}" which ` +
-          `collides with r.rawTable("${physical}") (feature "${clash.featureName}"). ` +
+          `collides with r.storeTable("${physical}") (feature "${clash.featureName}"). ` +
           `Pick a different tableName — both would emit CREATE TABLE "${physical}".`,
       );
     }
@@ -249,7 +249,7 @@ export function populateMetricsAndSecrets(state: RegistryState, feature: Feature
   }
 }
 
-// Explicit + multi-stream projections (source-entity indexed) + raw tables +
+// Explicit + multi-stream projections (source-entity indexed) + store tables +
 // unmanaged tables (both cross-feature-uniqueness-by-physical-name guarded).
 export function populateProjectionsAndTables(
   state: RegistryState,
@@ -300,15 +300,15 @@ export function populateProjectionsAndTables(
     state.multiStreamProjectionFeatureMap.set(qualified, feature.name);
   }
 
-  // Raw tables: aggregated by feature-local short name (unprefixed —
+  // Store tables: aggregated by feature-local short name (unprefixed —
   // these bypass the qualified-name namespace because they have no
   // event-stream binding to disambiguate). Reject cross-feature
   // duplicates at boot so the dev-server doesn't race two CREATE TABLE
   // statements that target the same physical table name. Two features
   // registering the same physical tableName would also race two CREATE
   // TABLE statements via migrate-runner.
-  for (const [rawName, rawDef] of Object.entries(feature.rawTables ?? {})) {
-    const existing = state.rawTableMap.get(rawName);
+  for (const [rawName, rawDef] of Object.entries(feature.storeTables ?? {})) {
+    const existing = state.storeTableMap.get(rawName);
     if (existing) {
       throw new Error(
         `Raw-table "${rawName}" registered by both feature "${existing.featureName}" and ` +
@@ -337,7 +337,7 @@ export function populateProjectionsAndTables(
       owner: rawName,
       featureName: feature.name,
     });
-    state.rawTableMap.set(rawName, { ...rawDef, featureName: feature.name });
+    state.storeTableMap.set(rawName, { ...rawDef, featureName: feature.name });
   }
 }
 

package/src/engine/registry-state.ts

@@ -29,7 +29,6 @@ import type {
   PreSaveHookFn,
   ProjectionDefinition,
   QueryHandlerDef,
-  RawTableDef,
   ReferenceDataDef,
   RegistrarExtensionDef,
   RegistrarExtensionRegistration,
@@ -37,6 +36,7 @@ import type {
   ScreenDefinition,
   SearchPayloadContributorFn,
   SecretKeyDefinition,
+  StoreTableDef,
   TreeActionDef,
   WorkspaceDefinition,
   WriteHandlerDef,
@@ -199,7 +199,7 @@ export type RegistryState = {
   projectionsBySource: Map<string, ProjectionDefinition[]>;
   multiStreamProjectionMap: Map<string, MultiStreamProjectionDefinition>;
   multiStreamProjectionFeatureMap: Map<string, string>;
-  rawTableMap: Map<string, RawTableDef>;
+  storeTableMap: Map<string, StoreTableDef>;
   physicalTableOwners: Map<string, { kind: "entity" | "raw"; owner: string; featureName: string }>;
   authClaimsHooks: AuthClaimsHookDef[];
   claimKeyMap: Map<string, ClaimKeyDefinition>;
@@ -260,7 +260,7 @@ export function createInitialState(): RegistryState {
     projectionsBySource: new Map(),
     multiStreamProjectionMap: new Map(),
     multiStreamProjectionFeatureMap: new Map(),
-    rawTableMap: new Map(),
+    storeTableMap: new Map(),
     physicalTableOwners: new Map(),
     authClaimsHooks: [],
     claimKeyMap: new Map(),

package/src/engine/types/feature.ts

@@ -125,18 +125,18 @@ export type SecretKeyHandle = {
   readonly name: string;
 };
 
-// --- Raw tables (declared by features via r.rawTable()) ---
+// --- Store tables (declared by features via r.storeTable()) ---
 // Post-drizzle-cut: unified with the former r.unmanagedTable() — both
 // carried the same reason/audit contract, differing only in whether the
-// table value was a legacy Drizzle PgTable (rawTable) or the framework-
+// table value was a legacy Drizzle PgTable (storeTable) or the framework-
 // native EntityTableMeta (unmanagedTable, consumed by migrate-runner).
-// EntityTableMeta was the forward-compatible shape, so rawTable adopted it.
+// EntityTableMeta was the forward-compatible shape, so storeTable adopted it.
 
-/** Options accepted by `r.rawTable()`. The `reason` is required so the
+/** Options accepted by `r.storeTable()`. The `reason` is required so the
  *  bypass leaves an audit trail at the registration site — reviewers can
  *  judge legitimacy without spelunking into history, and a future cleanup
  *  pass can find candidates for migration to `r.entity()`. */
-export type RawTableOptions = {
+export type StoreTableOptions = {
   /** Why this table needs to bypass the event-sourcing system. Examples:
    *  "imported from pre-ES system, read-only", "external Stripe webhook
    *  payload cache, write-only by webhook handler", "denormalised
@@ -149,22 +149,22 @@ export type RawTableOptions = {
   readonly piiEncryptedOnWrite?: true;
 };
 
-/** Per-feature raw-table registration. `meta` is the `EntityTableMeta`
+/** Per-feature store-table registration. `meta` is the `EntityTableMeta`
  *  (framework-native shape used by `migrate-runner`). Carries the
  *  bypass-justification reason but knows nothing about the owning
  *  feature — that's added when the registry aggregates entries
- *  cross-feature into `RawTableDef`. */
-export type RawTableEntry = {
+ *  cross-feature into `StoreTableDef`. */
+export type StoreTableEntry = {
   readonly name: string;
   readonly meta: EntityTableMeta;
   readonly reason: string;
   readonly piiEncryptedOnWrite?: true;
 };
 
-/** Registry-aggregated raw-table — the per-feature `RawTableEntry` plus
- *  the owning feature name. This is what `Registry.getAllRawTables()`
+/** Registry-aggregated store-table — the per-feature `StoreTableEntry` plus
+ *  the owning feature name. This is what `Registry.getAllStoreTables()`
  *  exposes to readers (dev-server, ops UIs). */
-export type RawTableDef = RawTableEntry & {
+export type StoreTableDef = StoreTableEntry & {
   readonly featureName: string;
 };
 
@@ -341,13 +341,13 @@ export type FeatureDefinition = {
   // den Hono-app (außerhalb /api/*). Pattern symmetrisch zu queryHandlers/
   // writeHandlers — Routes leben mit dem Feature, nicht im Bootstrap.
   readonly httpRoutes: Readonly<Record<string, HttpRouteDefinition>>;
-  // Raw tables declared via r.rawTable() — bypass the event-sourcing
+  // Store tables declared via r.storeTable() — bypass the event-sourcing
   // system. Keyed by feature-local short name (derived from
   // meta.tableName). The registry attaches featureName on aggregation,
-  // lifting RawTableEntry → RawTableDef. `kumiko schema generate`
+  // lifting StoreTableEntry → StoreTableDef. `kumiko schema generate`
   // aggregates these alongside r.entity()-derived metas to build the
   // full schema.
-  readonly rawTables: Readonly<Record<string, RawTableEntry>>;
+  readonly storeTables: Readonly<Record<string, StoreTableEntry>>;
   // Optional Zod-schema for env-vars this feature reads at runtime.
   // Declared via `r.envSchema(z.object({...}))`. `composeEnvSchema` reads
   // this to build one app-wide schema for boot-validation + dry-run
@@ -735,7 +735,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // The required `reason` string is the marker that justifies the bypass —
   // a non-empty string is the contract. If you can't write a reason,
   // declare data via `r.entity()` instead.
-  rawTable(meta: EntityTableMeta, options: RawTableOptions): void;
+  storeTable(meta: EntityTableMeta, options: StoreTableOptions): void;
 
   // Register the tree-actions schema for this feature — a map of
   // action-name → action-definition (with optional typed args). At-most-
@@ -894,12 +894,12 @@ export type Registry = {
   getProjectionsForSource(entityName: string): readonly ProjectionDefinition[];
   getAllProjections(): ReadonlyMap<string, ProjectionDefinition>;
 
-  // All r.rawTable() registrations across all features, keyed by
+  // All r.storeTable() registrations across all features, keyed by
   // feature-local short name. The dev-server iterates this alongside
   // implicit projections at boot. Cross-feature uniqueness is enforced
   // at registry-build — duplicate names from different features fail
   // the boot, so callers can rely on a flat keyspace.
-  getAllRawTables(): ReadonlyMap<string, RawTableDef>;
+  getAllStoreTables(): ReadonlyMap<string, StoreTableDef>;
 
   // Multi-stream projections registered via r.multiStreamProjection().
   // Keyed by qualified name. The server wires each into the event-dispatcher

package/src/engine/types/index.ts

@@ -67,13 +67,13 @@ export type {
   FeatureMetricType,
   FeatureRegistrar,
   MetricOptions,
-  RawTableDef,
-  RawTableEntry,
-  RawTableOptions,
   Registry,
   SecretKeyDefinition,
   SecretKeyHandle,
   SecretOptions,
+  StoreTableDef,
+  StoreTableEntry,
+  StoreTableOptions,
   UiHintOption,
   UiHints,
 } from "./feature";

package/src/migrations/pending-rebuilds.ts

@@ -200,7 +200,7 @@ export type EnqueueProjectionRebuildDeps = {
   readonly db: DbConnection;
   readonly registry: Registry;
   // Present + projection-rebuild job registered (jobs composed) → tracked,
-  // retryable job (read_job_runs + read_job_run_logs). Absent → inline rebuild.
+  // retryable job (read_job_runs + store_job_run_logs). Absent → inline rebuild.
   readonly jobRunner?: JobRunner;
 };
 

package/src/stack/push-entity-projection-tables.ts

@@ -9,7 +9,7 @@ const logInfo = (msg: string): void => console.log(msg);
 /**
  * Push all implicit-projection tables — one per `r.entity()` — that the
  * registry knows about. setupTestStack already handles explicit
- * projections, MSPs, and `r.rawTable()` declarations in its own loop;
+ * projections, MSPs, and `r.storeTable()` declarations in its own loop;
  * implicit projections are the missing piece for a fresh boot.
  *
  * Idempotent via `tableExists` so a persistent dev DB
@@ -20,7 +20,7 @@ const logInfo = (msg: string): void => console.log(msg);
  * Lives next to `setupTestStack` because both are stack-bootstrap
  * helpers that legitimately speak the `unsafe*`-DDL layer; the
  * Table-DDL Guard's stack/** allowlist is the single shared exemption
- * site. Apps still declare data via `r.entity()` / `r.rawTable()` and
+ * site. Apps still declare data via `r.entity()` / `r.storeTable()` and
  * never call this directly.
  */
 export async function pushEntityProjectionTables(