@cosmicdrift/kumiko-framework 0.48.1 → 0.50.0

package/src/migrations/__tests__/pending-rebuilds.integration.test.ts

@@ -162,6 +162,67 @@ describe("pending-rebuilds queue", () => {
 
   test("no markers, no queue → noop", async () => {
     const run = await runPendingRebuilds(testDb.db, registry);
-    expect(run).toEqual({ rebuilt: [], failed: [], unmapped: [] });
+    expect(run).toEqual({ rebuilt: [], failed: [], unmapped: [], unresolvedManaged: [] });
+  });
+
+  // #361: eine managed-Tabelle (Marker tragen nur managed), die in DIESEM Run
+  // geleert wurde, aber keine Projektion auflöst = owning-Feature fehlt in der
+  // Komposition → laut (unresolvedManaged), aber non-fatal (gedraint, kein Throw).
+  test("managed table emptied THIS run with no resolving projection → unresolvedManaged, still drained", async () => {
+    writeRebuildMarker(markerDir, "0003_orphan_managed.sql", ["read_orphan_projection"]);
+    const queued = await queueRebuildsFromMarkers(testDb.db, {
+      migrationsDir: markerDir,
+      appliedIds: ["0003_orphan_managed"],
+    });
+    expect(queued).toEqual(["read_orphan_projection"]);
+
+    const run = await runPendingRebuilds(testDb.db, registry, { thisRunTables: queued });
+    expect(run.unresolvedManaged).toEqual(["read_orphan_projection"]);
+    expect(run.unmapped).toEqual([]);
+    expect(run.rebuilt).toEqual([]);
+    expect(run.failed).toEqual([]);
+    // Trotz laut: gedraint → kein sticky-stuck Re-Apply.
+    expect(await listPendingRebuilds(testDb.db)).toEqual([]);
+  });
+
+  // #361: dieselbe unmapped-Tabelle, aber NICHT in thisRunTables (pre-existing
+  // pending aus einem früheren Run / evtl. altem unmanaged-Marker) → benign,
+  // still gedraint, NICHT als unresolvedManaged geflaggt (kein False-Positive).
+  test("pre-existing pending table not in thisRunTables → benign unmapped, not flagged", async () => {
+    writeRebuildMarker(markerDir, "0004_legacy.sql", ["read_legacy_table"]);
+    await queueRebuildsFromMarkers(testDb.db, {
+      migrationsDir: markerDir,
+      appliedIds: ["0004_legacy"],
+    });
+
+    // Re-Run ohne frisch gequeuete Tabellen (thisRunTables leer) — die Queue
+    // trägt nur den Altbestand.
+    const run = await runPendingRebuilds(testDb.db, registry, { thisRunTables: [] });
+    expect(run.unmapped).toEqual(["read_legacy_table"]);
+    expect(run.unresolvedManaged).toEqual([]);
+    expect(await listPendingRebuilds(testDb.db)).toEqual([]);
+  });
+
+  // #361: ein lauter unresolved-managed-Eintrag darf den auflösbaren Rebuild
+  // im selben Run nicht blockieren.
+  test("mixed run: resolvable projection rebuilt while an unresolved managed table is flagged", async () => {
+    await executor.create({ groupId: GROUP, name: "a" }, admin, tdb);
+    writeRebuildMarker(markerDir, "0005_mixed.sql", [
+      "read_pending_counts",
+      "read_orphan_projection",
+    ]);
+    const queued = await queueRebuildsFromMarkers(testDb.db, {
+      migrationsDir: markerDir,
+      appliedIds: ["0005_mixed"],
+    });
+
+    const run = await runPendingRebuilds(testDb.db, registry, { thisRunTables: queued });
+    expect(run.rebuilt).toEqual([
+      { projection: "pendingtest:projection:pending-counts", eventsProcessed: 1 },
+    ]);
+    expect(run.unresolvedManaged).toEqual(["read_orphan_projection"]);
+    expect(run.failed).toEqual([]);
+    expect(await listPendingRebuilds(testDb.db)).toEqual([]);
+    expect(await getCount()).toBe(1);
   });
 });

package/src/migrations/index.ts

@@ -14,6 +14,7 @@ export {
   type PendingRebuildRun,
   pendingRebuildsTable,
   queueRebuildsFromMarkers,
+  type RunPendingRebuildsOptions,
   runPendingRebuilds,
 } from "./pending-rebuilds";
 // tableName → projection-name, für den app-seitigen Projection-Rebuild.

package/src/migrations/pending-rebuilds.ts

@@ -17,6 +17,7 @@ import { deleteMany, selectMany, upsertOnConflict } from "../db/query";
 import { readRebuildMarker } from "../db/rebuild-marker";
 import { tableExists } from "../db/schema-inspection";
 import type { Registry } from "../engine/types";
+import { createFallbackLogger } from "../logging/utils";
 import { rebuildProjection } from "../pipeline";
 import { unsafePushTables } from "../stack";
 import { buildProjectionTableIndex } from "./projection-table-index";
@@ -78,37 +79,75 @@ export type PendingRebuildRun = {
   readonly rebuilt: readonly { readonly projection: string; readonly eventsProcessed: number }[];
   /** Fehlgeschlagene Projektionen — ihre Tabellen BLEIBEN pending. */
   readonly failed: readonly { readonly projection: string; readonly error: string }[];
-  /** Pending-Tabellen ohne registrierte Projektion — geräumt (kein Rebuild-Sinn). */
+  /** Pending-Tabellen ohne registrierte Projektion, die NICHT in diesem Run
+   *  frisch via Marker geleert wurden (pre-existing / Legacy-unmanaged-Marker)
+   *  — geräumt, still (nicht von echten Legacy-Tabellen unterscheidbar). */
   readonly unmapped: readonly string[];
+  /** In DIESEM Run via Marker geleerte managed-Tabellen ohne auflösbare
+   *  Projektion = das owning-Feature fehlt in der Komposition. Geräumt (kein
+   *  Stuck-Loop), aber LAUT geloggt — die Projektion ist jetzt leer. */
+  readonly unresolvedManaged: readonly string[];
+};
+
+export type RunPendingRebuildsOptions = {
+  /** Tabellen, die in DIESEM apply-Run frisch via Marker gequeued wurden
+   *  (Rückgabe von `queueRebuildsFromMarkers`). Marker tragen nur managed
+   *  Tabellen — eine davon ohne auflösbare Projektion ist ein echter Defekt
+   *  (fehlendes Feature) und wird laut gemeldet statt still geleert. Fehlt die
+   *  Option, wird jede unmapped Tabelle als pre-existing/benign behandelt
+   *  (Verhalten vor #361). */
+  readonly thisRunTables?: readonly string[];
 };
 
 /** Arbeitet die persistierte Queue ab: mappt Tabellen auf Projektionen,
  *  rebuildet jede betroffene Projektion und räumt ihre Tabellen erst nach
  *  ERFOLG aus der Queue. Fehlgeschlagene bleiben pending — der nächste
- *  apply (oder ein direkter Re-Call) holt sie nach. */
+ *  apply (oder ein direkter Re-Call) holt sie nach. Unmapped-Tabellen werden
+ *  geräumt (kein Stuck-Loop); die in diesem Run frisch geleerten managed-
+ *  Tabellen ohne Projektion zusätzlich laut gemeldet (`unresolvedManaged`). */
 export async function runPendingRebuilds(
   db: DbConnection,
   registry: Registry,
+  options: RunPendingRebuildsOptions = {},
 ): Promise<PendingRebuildRun> {
   const pending = await listPendingRebuilds(db);
-  if (pending.length === 0) return { rebuilt: [], failed: [], unmapped: [] };
+  if (pending.length === 0) {
+    return { rebuilt: [], failed: [], unmapped: [], unresolvedManaged: [] };
+  }
 
   const tableToProjection = buildProjectionTableIndex(registry);
+  const thisRun = new Set(options.thisRunTables ?? []);
   const byProjection = new Map<string, string[]>();
   const unmapped: string[] = [];
+  const unresolvedManaged: string[] = [];
   for (const tableName of pending) {
     const projection = tableToProjection.get(tableName);
     if (projection === undefined) {
-      unmapped.push(tableName);
+      // Marker tragen nur managed Tabellen (rebuild-marker.ts). Eine in DIESEM
+      // Run frisch geleerte Tabelle ohne auflösbare Projektion ist daher ein
+      // echter Defekt (owning-Feature fehlt in der Komposition) → laut. Pre-
+      // existing pending Tabellen sind nicht von alten unmanaged-Markern
+      // unterscheidbar → still drainen wie bisher (kein Hard-Throw, siehe #361).
+      if (thisRun.has(tableName)) unresolvedManaged.push(tableName);
+      else unmapped.push(tableName);
       continue;
     }
     byProjection.set(projection, [...(byProjection.get(projection) ?? []), tableName]);
   }
 
-  // Tabellen ohne Projektion: gleiche Semantik wie der bisherige Skip beim
-  // Apply — aber explizit geräumt, damit die Queue nicht ewig wächst.
-  if (unmapped.length > 0) {
-    await clearPendingRebuilds(db, unmapped);
+  // Beide Klassen räumen: die Queue darf nicht ewig wachsen, und ein Re-Apply
+  // darf nicht sticky-stuck werfen. Die Lautstärke liegt im Log + Return-Feld,
+  // nicht im Liegenlassen.
+  const drained = [...unmapped, ...unresolvedManaged];
+  if (drained.length > 0) {
+    await clearPendingRebuilds(db, drained);
+  }
+
+  if (unresolvedManaged.length > 0) {
+    createFallbackLogger("migrations:pending-rebuilds").error(
+      `${unresolvedManaged.length} managed projection table(s) emptied by a migration in this run have no registered projection — the owning feature is likely missing from the composition. They are now EMPTY and were NOT rebuilt: ${unresolvedManaged.join(", ")}. Restore the owning feature or rebuild the projection manually.`,
+      { tables: unresolvedManaged },
+    );
   }
 
   const rebuilt: { projection: string; eventsProcessed: number }[] = [];
@@ -122,5 +161,5 @@ export async function runPendingRebuilds(
       failed.push({ projection, error: e instanceof Error ? e.message : String(e) });
     }
   }
-  return { rebuilt, failed, unmapped };
+  return { rebuilt, failed, unmapped, unresolvedManaged };
 }

package/src/pipeline/dispatcher.ts

@@ -298,9 +298,9 @@ export function createDispatcher(
     // (e.g. system-privileged lookups that bypass field-access read filters).
     const bridgeSink = afterCommitHooks ?? [];
     const bridge = {
-      query: (targetType: string, payload: unknown) => executeQuery(targetType, payload, user, tx),
+      query: (targetType: string, payload: unknown) => executeQuery(targetType, payload, user, tx), // @wrapper-known semantic-alias
       queryAs: (asUser: SessionUser, targetType: string, payload: unknown) =>
-        executeQuery(targetType, payload, asUser, tx),
+        executeQuery(targetType, payload, asUser, tx), // @wrapper-known semantic-alias
       write: async (targetType: string, payload: unknown) => {
         const res = await executeWrite(targetType, payload, user, tx, bridgeSink);
         return res;
@@ -476,7 +476,7 @@ export function createDispatcher(
           user.tenantId,
           reducer,
           initial,
-          { upcastEvent: (event) => upcastStoredEvent(event, upcasters, upcastCtx) },
+          { upcastEvent: (event) => upcastStoredEvent(event, upcasters, upcastCtx) }, // @wrapper-known semantic-alias
         );
       },
       queryProjection: async <T = Record<string, unknown>>(
@@ -521,7 +521,7 @@ export function createDispatcher(
       // handler surface just forwards the call so both entry points (login
       // handler via ctx.resolveAuthClaims, switch-tenant route via
       // dispatcher.resolveAuthClaims) cannot drift.
-      resolveAuthClaims: (claimsUser: SessionUser) => resolveAuthClaimsFn(claimsUser),
+      resolveAuthClaims: (claimsUser: SessionUser) => resolveAuthClaimsFn(claimsUser), // @wrapper-known semantic-alias
 
       // Feature-effective check for in-handler opt-in logic. Scope:
       // **current user's tenant** — for cross-tenant lookups (rare,
@@ -1387,7 +1387,7 @@ export function createDispatcher(
     return {
       db,
       queryAs: (asUser: SessionUser, qn: string, payload: unknown) =>
-        executeQuery(qn, payload, asUser),
+        executeQuery(qn, payload, asUser), // @wrapper-known semantic-alias
       ...(configAccessor && { config: configAccessor }),
     };
   }

package/src/pipeline/lifecycle-pipeline.ts

@@ -286,8 +286,8 @@ export function createLifecycleHooks(
         payload: result,
         context,
         entityName: result.entityName,
-        getHandlerHooks: (n) => registry.getPostSaveHooks(n, phase, eff),
-        getEntityHooks: (n) => registry.getEntityPostSaveHooks(n, phase, eff),
+        getHandlerHooks: (n) => registry.getPostSaveHooks(n, phase, eff), // @wrapper-known semantic-alias
+        getEntityHooks: (n) => registry.getEntityPostSaveHooks(n, phase, eff), // @wrapper-known semantic-alias
         systemHookDefs: systemHooks.postSave,
         phaseLabel: `postSave:${phase}`,
         hookPhase: phase,
@@ -328,8 +328,8 @@ export function createLifecycleHooks(
         payload,
         context,
         entityName: payload.entityName,
-        getHandlerHooks: (n) => registry.getPostDeleteHooks(n, phase, eff),
-        getEntityHooks: (n) => registry.getEntityPostDeleteHooks(n, phase, eff),
+        getHandlerHooks: (n) => registry.getPostDeleteHooks(n, phase, eff), // @wrapper-known semantic-alias
+        getEntityHooks: (n) => registry.getEntityPostDeleteHooks(n, phase, eff), // @wrapper-known semantic-alias
         systemHookDefs: systemHooks.postDelete,
         phaseLabel: `postDelete:${phase}`,
         hookPhase: phase,

package/src/stack/table-helpers.ts

@@ -129,6 +129,7 @@ export async function unsafePushTables(
   }
 }
 
+// @wrapper-known semantic-alias
 function renderColumnType(col: ColumnMeta): string {
   return pgTypeToSqlType(col.pgType);
 }

package/src/time/tz-context.ts

@@ -74,9 +74,9 @@ export function createTzContext(options: TzContextOptions = {}): TzContext {
   return {
     tenant,
     user,
-    now: () => T.Now.instant(),
-    nowIn: (tz: string) => T.Now.zonedDateTimeISO(tz),
-    today: (tz: string) => T.Now.plainDateISO(tz),
+    now: () => T.Now.instant(), // @wrapper-known semantic-alias
+    nowIn: (tz: string) => T.Now.zonedDateTimeISO(tz), // @wrapper-known semantic-alias
+    today: (tz: string) => T.Now.plainDateISO(tz), // @wrapper-known semantic-alias
     todayRange: (tz: string) => {
       const today = T.Now.plainDateISO(tz);
       const startZdt = today.toZonedDateTime({ timeZone: tz });

package/src/utils/compare.ts

@@ -0,0 +1,10 @@
+// Locale-independent string ordering for sorts that feed byte-exact serialized
+// artifacts (manifest JSON, snapshot.json, generated migration SQL). Unlike
+// String.localeCompare — whose order depends on the runner's ICU locale and so
+// can drift between a macOS dev box and Linux CI (#330) — this compares by
+// UTF-16 code unit, which is stable across machines and, for the BMP identifier
+// strings we sort here (table / column / feature / qualified names), equals
+// codepoint order.
+export function compareByCodepoint(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/utils/ids.ts

@@ -11,6 +11,7 @@ import { v7 } from "uuid";
 // Do NOT use this for security tokens (CSRF, session, API keys). The
 // timestamp prefix leaks creation time and shrinks unpredictable
 // entropy from 122 to 74 bits — use `generateToken` from api/tokens.ts.
+// @wrapper-known semantic-alias
 export function generateId(): string {
   return v7();
 }

package/src/utils/index.ts

@@ -1,5 +1,6 @@
 export { assertUnreachable } from "./assert";
 export { toSnakeCase } from "./case";
+export { compareByCodepoint } from "./compare";
 export { readPositiveIntEnv } from "./env-parse";
 export { generateId } from "./ids";
 export { isPlainObject } from "./is-plain-object";