@cosmicdrift/kumiko-framework 0.48.1 → 0.51.0

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

@@ -30,6 +30,7 @@ import {
   unsafePushTables,
 } from "../../stack";
 import {
+  enqueueProjectionRebuild,
   listPendingRebuilds,
   queueRebuildsFromMarkers,
   runPendingRebuilds,
@@ -162,6 +163,88 @@ 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);
+  });
+});
+
+// #362: der framework-Helper. Ohne jobs-Feature (kein jobRunner) rebuildet er
+// synchron inline — das heutige Verhalten, garantiert framework-pur. Der
+// dispatch-Pfad (mit jobs) lebt in jobs/__tests__/projection-rebuild-job.*.
+describe("enqueueProjectionRebuild — inline fallback (no jobs feature)", () => {
+  test("without a jobRunner, rebuilds the projection synchronously", async () => {
+    await executor.create({ groupId: GROUP, name: "a" }, admin, tdb);
+    await executor.create({ groupId: GROUP, name: "b" }, admin, tdb);
+
+    const outcome = await enqueueProjectionRebuild("pendingtest:projection:pending-counts", {
+      db: testDb.db,
+      registry,
+    });
+
+    expect(outcome.mode).toBe("inline");
+    if (outcome.mode === "inline") {
+      expect(outcome.result.eventsProcessed).toBe(2);
+    }
+    expect(await getCount()).toBe(2);
   });
 });

package/src/migrations/index.ts

@@ -10,10 +10,15 @@ export {
 // Persistente Pending-Rebuild-Queue (survives Rebuild-Failures + Crashes).
 export {
   createPendingRebuildsTable,
+  type EnqueueProjectionRebuildDeps,
+  type EnqueueProjectionRebuildResult,
+  enqueueProjectionRebuild,
   listPendingRebuilds,
   type PendingRebuildRun,
+  PROJECTION_REBUILD_JOB,
   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,7 +17,9 @@ 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 { rebuildProjection } from "../pipeline";
+import type { JobRunner } from "../jobs";
+import { createFallbackLogger } from "../logging/utils";
+import { type RebuildResult, rebuildProjection } from "../pipeline";
 import { unsafePushTables } from "../stack";
 import { buildProjectionTableIndex } from "./projection-table-index";
 
@@ -78,37 +80,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 +162,39 @@ export async function runPendingRebuilds(
       failed.push({ projection, error: e instanceof Error ? e.message : String(e) });
     }
   }
-  return { rebuilt, failed, unmapped };
+  return { rebuilt, failed, unmapped, unresolvedManaged };
+}
+
+// Qualified name of the framework-provided projection-rebuild job. Registered
+// by the `jobs` bundled-feature (createJobsFeature) → available whenever jobs
+// is composed. A jobs-less boot has no jobRunner and rebuilds inline instead.
+export const PROJECTION_REBUILD_JOB = "jobs:job:projection-rebuild";
+
+export type EnqueueProjectionRebuildResult =
+  | { readonly mode: "dispatched"; readonly bullJobId: string }
+  | { readonly mode: "inline"; readonly result: RebuildResult };
+
+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.
+  readonly jobRunner?: JobRunner;
+};
+
+/** Triggert einen Single-Projection-Rebuild. Mit `jobs`-Feature (jobRunner +
+ *  registriertem Job) als getrackter, retrybarer Job; ohne jobs synchron inline
+ *  (heutiges Verhalten). Capability-Detektion über `registry.getJob`, NICHT
+ *  `hasFeature` — deterministisch und ohne Toggle-Runtime-Abhängigkeit. */
+export async function enqueueProjectionRebuild(
+  projection: string,
+  deps: EnqueueProjectionRebuildDeps,
+): Promise<EnqueueProjectionRebuildResult> {
+  const { db, registry, jobRunner } = deps;
+  if (jobRunner !== undefined && registry.getJob(PROJECTION_REBUILD_JOB) !== undefined) {
+    const bullJobId = await jobRunner.dispatch(PROJECTION_REBUILD_JOB, { projection });
+    return { mode: "dispatched", bullJobId };
+  }
+  const result = await rebuildProjection(projection, { db, registry });
+  return { mode: "inline", result };
 }

package/src/pipeline/dispatcher.ts

@@ -278,7 +278,11 @@ export function createDispatcher(
     // Mirror notify: only built when the config feature wired its factory.
     const config =
       context._configAccessorFactory && db
-        ? context._configAccessorFactory({ user: { id: user.id, tenantId: user.tenantId }, db })
+        ? context._configAccessorFactory({
+            user: { id: user.id, tenantId: user.tenantId },
+            db,
+            secrets: context.secrets,
+          })
         : undefined;
 
     // Observability — feature-bound metrics handle, so ctx.metrics.inc("foo")
@@ -298,9 +302,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 +480,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 +525,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,
@@ -1382,12 +1386,16 @@ export function createDispatcher(
     }
     const db = createTenantDb(dbSource, user.tenantId, "tenant", context.tracer, context.meter);
     const configAccessor = context._configAccessorFactory
-      ? context._configAccessorFactory({ user: { id: user.id, tenantId: user.tenantId }, db })
+      ? context._configAccessorFactory({
+          user: { id: user.id, tenantId: user.tenantId },
+          db,
+          secrets: context.secrets,
+        })
       : undefined;
     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";