@cosmicdrift/kumiko-bundled-features 0.156.2 → 0.157.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.156.2",
+  "version": "0.157.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -116,11 +116,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.156.2",
-    "@cosmicdrift/kumiko-framework": "0.156.2",
-    "@cosmicdrift/kumiko-headless": "0.156.2",
-    "@cosmicdrift/kumiko-renderer": "0.156.2",
-    "@cosmicdrift/kumiko-renderer-web": "0.156.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.157.0",
+    "@cosmicdrift/kumiko-framework": "0.157.0",
+    "@cosmicdrift/kumiko-headless": "0.157.0",
+    "@cosmicdrift/kumiko-renderer": "0.157.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.157.0",
     "@mollie/api-client": "^4.5.0",
     "imapflow": "^1.3.3",
     "mailparser": "^3.9.8",

package/src/auth-mfa/__tests__/verify.integration.test.ts

@@ -90,15 +90,26 @@ async function enableMfaFor(idSeed: number): Promise<{
     { setupToken: start.setupToken, code: currentTotpCode(secret) },
     user,
   );
-  // verify.write.ts re-checks tenant membership the same way login.write.ts
-  // does — without a seeded row here every verify would now hit the
-  // membership-revoked gate below instead of the scenario each test means
-  // to exercise.
+  // verify.write.ts re-checks tenant membership AND the user's own row
+  // (status gate) the way login.write.ts does — auth-mfa never writes a
+  // read_users row itself (enableStart/enableConfirm only touch user-mfa),
+  // so both need seeding here, not just per-test where a scenario cares.
   await seedRow(stack.db, tenantMembershipsTable, {
     userId: user.id,
     tenantId: user.tenantId,
     roles: JSON.stringify(["User"]),
   });
+  await seedRow(stack.db, userTable, {
+    id: user.id,
+    tenantId: user.tenantId,
+    email: `user-${user.id}@example.com`,
+    passwordHash: "h",
+    displayName: `Test User ${idSeed}`,
+    locale: "de",
+    emailVerified: true,
+    roles: "[]",
+    status: USER_STATUS.Active,
+  });
   return { user, secret, recoveryCodes: start.recoveryCodes };
 }
 
@@ -247,21 +258,8 @@ describe("mfa verify — re-checks account state the way login.write.ts does", (
     const { user, secret } = await enableMfaFor(6);
     const challengeToken = challengeFor(user.id, user.tenantId);
 
-    // auth-mfa never writes a read_users row itself (enableMfaFor only
-    // drives enable-start/enable-confirm) — seed one so the status gate has
-    // a row to actually flip, then flip it to simulate a restriction landing
-    // between login and verify.
-    await seedRow(stack.db, userTable, {
-      id: user.id,
-      tenantId: user.tenantId,
-      email: `user-${user.id}@example.com`,
-      passwordHash: "h",
-      displayName: "Restricted User",
-      locale: "de",
-      emailVerified: true,
-      roles: "[]",
-      status: USER_STATUS.Active,
-    });
+    // enableMfaFor already seeded the user row Active — flip it to simulate
+    // a restriction landing between login and verify.
     await asRawClient(stack.db).unsafe(
       `UPDATE "${userTable.tableName}" SET status = $1 WHERE id = $2`,
       [USER_STATUS.Restricted, user.id],

package/src/auth-mfa/handlers/verify.write.ts

@@ -139,6 +139,7 @@ export function createMfaVerifyHandler(opts: MfaVerifyOptions) {
       // now. Deliberately NOT re-checking strictEmailVerification here:
       // MfaVerifyOptions has no such flag, and email verification can't
       // regress between login and verify within the 10-minute window.
+      if (!userRow) return invalidChallengeToken();
       if (
         userRow?.status === USER_STATUS.Restricted ||
         userRow?.status === USER_STATUS.DeletionRequested ||

package/src/cap-counter/__tests__/entity-ddl.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from "bun:test";
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import { capCounterEntity } from "../entity";
+
+function pgTypeOf(table: unknown, dbName: string): string | undefined {
+  const cols = (table as { columns?: ReadonlyArray<{ name: string; pgType?: string }> }).columns;
+  return cols?.find((c) => c.name === dbName)?.pgType;
+}
+
+describe("capCounterEntity — DDL (#1205 regression)", () => {
+  test("value column is bigint, not double precision", () => {
+    const table = buildEntityTable("cap-counter", capCounterEntity);
+    expect(pgTypeOf(table, "value")).toBe("bigint");
+  });
+});

package/src/cap-counter/entity.ts

@@ -1,6 +1,6 @@
 import {
+  createBigIntField,
   createEntity,
-  createNumberField,
   createTextField,
   createTimestampField,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -41,7 +41,7 @@ export const capCounterEntity = createEntity({
   table: "read_cap_counters",
   fields: {
     capName: createTextField({ required: true, maxLength: 100, sortable: true, searchable: true }),
-    value: createNumberField({ required: true, default: 0 }),
+    value: createBigIntField({ required: true, default: 0 }),
     periodStart: createTimestampField({ required: true }),
     lastSoftWarnedAt: createTimestampField(),
   },

package/src/delivery/feature.ts

@@ -22,7 +22,7 @@ import {
 export function createDeliveryFeature(): FeatureDefinition {
   return defineFeature("delivery", (r) => {
     r.describe(
-      "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). It stores per-user channel preferences in the `notification-preference` entity, logs every attempt to `read_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything.",
+      "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). It stores per-user channel preferences in the `notification-preference` entity, logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything.",
     );
     r.uiHints({
       displayLabel: "Notifications \u00b7 Dispatch Core",
@@ -36,7 +36,7 @@ export function createDeliveryFeature(): FeatureDefinition {
     r.entity("notification-preference", notificationPreferenceEntity, {
       table: notificationPreferencesTable,
     });
-    r.rawTable(deliveryAttemptsTableMeta, {
+    r.storeTable(deliveryAttemptsTableMeta, {
       reason: "read_side.delivery_attempt_log",
     });
 

package/src/delivery/tables.ts

@@ -28,7 +28,7 @@ import {
 // PK = event aggregate-id (uuid). Keeps the projection row linked back to
 // its event stream 1:1 — same convention as jobRunsTable + tenantSecretsTable.
 // Event replays stay idempotent (primary-key conflict instead of duplicate rows).
-export const deliveryAttemptsTable = pgTable("read_delivery_attempts", {
+export const deliveryAttemptsTable = pgTable("store_delivery_attempts", {
   id: uuid("id").primaryKey(),
   tenantId: uuid("tenant_id").notNull(),
   notificationType: text("notification_type").notNull(),
@@ -53,7 +53,7 @@ export const deliveryAttemptsTable = pgTable("read_delivery_attempts", {
 // pgTable bleibt source-of-truth für Query-API; Phase 4 leitet das pgTable
 // aus dieser Meta ab.
 export const deliveryAttemptsTableMeta: EntityTableMeta = defineUnmanagedTable({
-  tableName: "read_delivery_attempts",
+  tableName: "store_delivery_attempts",
   columns: [
     { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
     { name: "tenant_id", pgType: "uuid", notNull: true },

package/src/feature-toggles/feature.ts

@@ -39,7 +39,7 @@ export function createFeatureTogglesFeature(
 ): FeatureDefinition {
   return defineFeature("feature-toggles", (r) => {
     r.describe(
-      'Persists per-feature enabled/disabled state in the `read_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: "per-instance"` syncs the snapshot across instances whenever a `toggle-set` event is appended.',
+      'Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: "per-instance"` syncs the snapshot across instances whenever a `toggle-set` event is appended.',
     );
     r.uiHints({
       displayLabel: "Feature Toggles · Operator Switches",

package/src/feature-toggles/global-feature-state-table.ts

@@ -15,7 +15,7 @@ import {
 // name IS the identity here. No tenantId: this is a global override that
 // applies across every tenant (per-tenant toggles are intentionally out of
 // scope, see core-feature-toggles.md).
-export const globalFeatureStateTable = pgTable("read_global_feature_state", {
+export const globalFeatureStateTable = pgTable("store_global_feature_state", {
   featureName: text("feature_name").primaryKey(),
   enabled: boolean("enabled").notNull(),
   // Optimistic-lock column. The set-handler reads the existing row, then

package/src/inbound-mail-foundation/__tests__/feature.test.ts

@@ -44,7 +44,7 @@ describe("inboundMailFoundationFeature — shape", () => {
   test("SyncCursor + SeenMessage sind unmanaged (NICHT event-sourced, Plan §3.4)", () => {
     // Drift-Pin: als r.entity würden die Tick-State-Tabellen (a) das
     // Event-Log fluten und (b) beim Projection-Rebuild gewischt.
-    const unmanaged = Object.keys(inboundMailFoundationFeature.rawTables);
+    const unmanaged = Object.keys(inboundMailFoundationFeature.storeTables);
     expect(unmanaged.length).toBe(2);
   });
 });

package/src/inbound-mail-foundation/entities.ts

@@ -111,7 +111,7 @@ export const MAIL_THREAD_PII_FIELDS = collectPiiSubjectFields(mailThreadEntity);
  *  Write-locked auf privileged — nur Foundation-Handler/Supervisor
  *  schreiben, kein Tenant-Request. */
 export const syncCursorEntity = createEntity({
-  table: "read_mail_sync_cursors",
+  table: "store_mail_sync_cursors",
   softDelete: false,
   fields: {
     accountId: createTextField({
@@ -141,7 +141,7 @@ export const syncCursorEntity = createEntity({
  *  ingest-handler prüft zuerst hier (cheap), der Stream-Scan bleibt
  *  Defense-in-depth. */
 export const seenMessageEntity = createEntity({
-  table: "read_mail_seen_messages",
+  table: "store_mail_seen_messages",
   softDelete: false,
   fields: {
     accountId: createTextField({
@@ -164,5 +164,9 @@ export const seenMessageEntity = createEntity({
 // Plain EntityTableMeta (kein branded EntityTable) — unmanaged Direct-
 // Write-Stores, Handler schreiben via ctx.db (siehe user-session.ts-
 // Rationale).
-export const syncCursorTable = buildEntityTableMeta("mail-sync-cursor", syncCursorEntity);
-export const seenMessageTable = buildEntityTableMeta("mail-seen-message", seenMessageEntity);
+export const syncCursorTable = buildEntityTableMeta("mail-sync-cursor", syncCursorEntity, {
+  source: "unmanaged",
+});
+export const seenMessageTable = buildEntityTableMeta("mail-seen-message", seenMessageEntity, {
+  source: "unmanaged",
+});

package/src/inbound-mail-foundation/feature.ts

@@ -156,12 +156,12 @@ export const inboundMailFoundationFeature = defineFeature(INBOUND_MAIL_FOUNDATIO
   });
 
   // Sync-Maschinerie: hochfrequenter Tick-State, bewusst NICHT
-  // event-sourced — r.rawTable hält die Migration-DDL, nimmt die
+  // event-sourced — r.storeTable hält die Migration-DDL, nimmt die
   // Tabellen aber aus dem Projection-Rebuild (#494/#498-Klasse).
-  r.rawTable(syncCursorTable, {
+  r.storeTable(syncCursorTable, {
     reason: "read_side.mail_sync_cursors_direct_write",
   });
-  r.rawTable(seenMessageTable, {
+  r.storeTable(seenMessageTable, {
     reason: "read_side.mail_seen_messages_direct_write",
   });
 

package/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -2,7 +2,7 @@
 // (watch-callback + fetchSince-Sync). Nimmt eine normalisierte
 // RawInboundMessage und macht atomic in EINER TX:
 //
-//   1. Idempotency-Check (cheap: read_mail_seen_messages; Defense-in-
+//   1. Idempotency-Check (cheap: store_mail_seen_messages; Defense-in-
 //      depth: Stream-Existenz auf der deterministic aggregateId).
 //   2. threadKey-Normalisierung (Provider-Thread-ID bevorzugt, sonst
 //      References-Chain-Root, sonst Message-ID = Single-Message-Thread).
@@ -115,7 +115,7 @@ export const ingestMessageHandler: WriteHandlerDef = {
     //    ein früherer ingest NACH dem append aber VOR dem seen-insert
     //    gestorben ist (kann in einer TX nicht passieren — aber der
     //    Check ist billig und macht den Handler rebuild-robust falls
-    //    read_mail_seen_messages je getruncated wird).
+    //    store_mail_seen_messages je getruncated wird).
     // ---------------------------------------------------------------
     const seenRows = await selectMany(ctx.db.raw, seenMessageTable, {
       accountId: payload.accountId,

package/src/inbound-mail-foundation/retention-sweep.ts

@@ -13,7 +13,7 @@
 //     loadAggregate leer → received wird gar nicht erst repliziert. Gleiches
 //     Muster wie tenant-destroy-hook, nur per-Row-cutoff statt ganzer Tenant.
 //
-//   read_mail_seen_messages (unmanaged, direct-write, nicht event-sourced):
+//   store_mail_seen_messages (unmanaged, direct-write, nicht event-sourced):
 //     Dedup-Anker braucht nur das Backfill-/Replay-Fenster → seenAt-cutoff
 //     via plain deleteMany, kein Stream/Archiv. Gescoped direkt über die
 //     tenant_id-Spalte der Tabelle (table-builder-Konvention), kein Account-Join.

package/src/inbound-mail-foundation/types.ts

@@ -92,7 +92,7 @@ export type RawInboundMessage = {
 
 /** Provider-opaker Cursor: IMAP {uidValidity,lastUid} · Graph {deltaLink}
  *  · Gmail {historyId}. Foundation persisted ihn JSON-stringified in
- *  read_mail_sync_cursors, interpretiert ihn nie. */
+ *  store_mail_sync_cursors, interpretiert ihn nie. */
 export type SyncCursorPayload = Readonly<Record<string, unknown>>;
 
 export type InboundFetchResult = {

package/src/inbound-mail-foundation/watch-supervisor.ts

@@ -63,7 +63,7 @@ export type InboundMailSupervisorDeps = {
    *  Credential-Reads der Provider). */
   readonly providerCtx: InboundMailContext;
   /** App-DB — direct reads auf read_mail_accounts (Account-Snapshot)
-   *  + direct writes auf read_mail_sync_cursors (unmanaged store). */
+   *  + direct writes auf store_mail_sync_cursors (unmanaged store). */
   readonly db: DbConnection;
   /** Standard-Dispatcher mit SystemUser — trägt ingest-message +
    *  update-account. */

package/src/jobs/__tests__/entity-ddl.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from "bun:test";
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import { jobRunEntity } from "../job-run-table";
+
+function pgTypeOf(table: unknown, dbName: string): string | undefined {
+  const cols = (table as { columns?: ReadonlyArray<{ name: string; pgType?: string }> }).columns;
+  return cols?.find((c) => c.name === dbName)?.pgType;
+}
+
+describe("jobRunEntity — DDL (#1205 regression)", () => {
+  test("duration column is integer, not double precision", () => {
+    const table = buildEntityTable("read_job_runs", jobRunEntity);
+    expect(pgTypeOf(table, "duration")).toBe("integer");
+  });
+});

package/src/jobs/__tests__/reindex-entity-job.integration.test.ts

@@ -0,0 +1,107 @@
+// #1215: the `jobs` feature registers `reindexEntity` as a manual + perTenant
+// job. perTenant jobs fan out through a BullMQ wrapper that needs
+// `getActiveTenantIds` (job-runner.ts) — setupTestStack's jobRunner doesn't
+// wire that, so this calls the exported handler directly with a constructed
+// context instead of going through jobRunner.dispatch(), same as
+// inbound-mail-foundation's retention job test calls its sweep function
+// directly rather than round-tripping through the queue.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  buildEntityTable,
+  createEventStoreExecutor,
+  createTenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createJobsFeature } from "../feature";
+import { reindexEntityJob } from "../handlers/reindex-entity.job";
+
+// Resolved job name — operators trigger this via jobs:write:trigger with
+// { jobName: "jobs:job:reindex-entity", payload: { entity: "..." } }.
+const REINDEX_ENTITY_JOB = "jobs:job:reindex-entity";
+
+const widgetEntity = createEntity({
+  table: "read_reindex_job_widgets",
+  fields: {
+    name: createTextField({ required: true, searchable: true }),
+  },
+});
+
+const widgetTable = buildEntityTable("widget", widgetEntity);
+
+const widgetFeature = defineFeature("reindex-job-test", (r) => {
+  r.entity("widget", widgetEntity);
+});
+
+let stack: TestStack;
+const admin = TestUsers.admin;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [widgetFeature, createJobsFeature()] });
+  await unsafeCreateEntityTable(stack.db, widgetEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("jobs feature: reindexEntity registration", () => {
+  test("registers reindexEntity as jobs:job:reindex-entity — the name jobs:write:trigger dispatches by", () => {
+    const job = stack.registry.getJob(REINDEX_ENTITY_JOB);
+    expect(job).toBeDefined();
+    expect(job?.handler).toBe(reindexEntityJob);
+    expect(job?.perTenant).toBe(true);
+    expect(job?.trigger).toEqual({ manual: true });
+  });
+});
+
+describe("reindexEntityJob", () => {
+  test("indexes rows for the tenant resolved from ctx.systemUser", async () => {
+    const executor = createEventStoreExecutor(widgetTable, widgetEntity, { entityName: "widget" });
+    const tenantDb = createTenantDb(stack.db, admin.tenantId, "system");
+    const created = await executor.create({ name: "Job Backfillable Widget" }, admin, tenantDb);
+    if (!created.isSuccess) throw new Error("seed failed");
+
+    // No stack.eventDispatcher.runOnce() — row was never indexed live.
+    const preResults = await stack.search.search(admin.tenantId, "backfillable", {
+      filterType: "widget",
+    });
+    expect(preResults).toHaveLength(0);
+
+    await reindexEntityJob(
+      { entity: "widget" },
+      { db: stack.db, registry: stack.registry, searchAdapter: stack.search, systemUser: admin },
+    );
+
+    const postResults = await stack.search.search(admin.tenantId, "backfillable", {
+      filterType: "widget",
+    });
+    expect(postResults.some((r) => r.entityId === created.data.id)).toBe(true);
+  });
+
+  test("skips silently when no tenant is resolvable (fan-out misfire)", async () => {
+    await expect(
+      reindexEntityJob(
+        { entity: "widget" },
+        { db: stack.db, registry: stack.registry, searchAdapter: stack.search },
+      ),
+    ).resolves.toBeUndefined();
+  });
+
+  test("throws when ctx.searchAdapter is missing", async () => {
+    await expect(
+      reindexEntityJob(
+        { entity: "widget" },
+        { db: stack.db, registry: stack.registry, systemUser: admin },
+      ),
+    ).rejects.toThrow(/searchAdapter/);
+  });
+});

package/src/jobs/feature.ts

@@ -17,6 +17,7 @@ import {
   projectionRebuildJob,
   projectionRebuildPayloadSchema,
 } from "./handlers/projection-rebuild.job";
+import { reindexEntityJob, reindexEntityPayloadSchema } from "./handlers/reindex-entity.job";
 import { retryWrite } from "./handlers/retry.write";
 import { triggerWrite } from "./handlers/trigger.write";
 import { JOBS_I18N } from "./i18n";
@@ -30,7 +31,7 @@ import { jobRunLogsTable, jobRunLogsTableMeta, jobRunsTable } from "./job-run-ta
 export function createJobsFeature(): FeatureDefinition {
   return defineFeature("jobs", (r) => {
     r.describe(
-      "Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution appends `run-started`, `run-completed`, and `run-failed` events to the `jobRun` aggregate stream, which two inline projections materialize into `read_job_runs` (current status + duration) and `read_job_run_logs` (per-line log rows). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list` and `jobs:query:details` for the operator UI.",
+      "Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution appends `run-started`, `run-completed`, and `run-failed` events to the `jobRun` aggregate stream, which two inline projections materialize into `read_job_runs` (current status + duration) and `store_job_run_logs` (per-line log rows). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list` and `jobs:query:details` for the operator UI.",
     );
     r.uiHints({
       displayLabel: "Jobs · Audit & Operator UI",
@@ -38,7 +39,7 @@ export function createJobsFeature(): FeatureDefinition {
       recommended: false,
     });
     r.systemScope();
-    r.rawTable(jobRunLogsTableMeta, {
+    r.storeTable(jobRunLogsTableMeta, {
       reason: "read_side.job_run_logs",
     });
     // Events-only aggregate: "jobRun" has no r.entity registration, because
@@ -174,6 +175,16 @@ export function createJobsFeature(): FeatureDefinition {
       projectionRebuildJob,
     );
 
+    // Retroactive search backfill (#1206/#1215) — manual + perTenant, so one
+    // `jobs:write:trigger` call with { entity } fans out to every active
+    // tenant (job-runner.ts perTenant dispatch applies to manual triggers
+    // too, not just cron).
+    r.job(
+      "reindexEntity",
+      { trigger: { manual: true }, perTenant: true, schema: reindexEntityPayloadSchema },
+      reindexEntityJob,
+    );
+
     const handlers = {
       trigger: r.writeHandler(triggerWrite),
       retry: r.writeHandler(retryWrite),

package/src/jobs/handlers/reindex-entity.job.ts

@@ -0,0 +1,49 @@
+// Manual, perTenant backfill job (#1206/#1215) — indexes existing rows for
+// an entity that only got `searchable: true` after rows already existed.
+// perTenant fan-out (job-runner.ts) also applies to a manual dispatch, not
+// just cron: one `jobs:write:trigger` call with { entity } re-runs once per
+// active tenant.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { JobHandlerFn } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { reindexEntity } from "@cosmicdrift/kumiko-framework/search";
+import { z } from "zod";
+
+export const reindexEntityPayloadSchema = z.object({
+  entity: z.string().min(1),
+});
+
+export const reindexEntityJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
+  const { entity } = reindexEntityPayloadSchema.parse(rawPayload);
+  if (!ctx.db) {
+    throw new InternalError({
+      message: "[jobs:reindex-entity] ctx.db missing — job context requires a database connection.",
+    });
+  }
+  if (!ctx.registry) {
+    throw new InternalError({
+      message: "[jobs:reindex-entity] ctx.registry missing — job context requires the registry.",
+    });
+  }
+  if (!ctx.searchAdapter) {
+    throw new InternalError({
+      message:
+        "[jobs:reindex-entity] ctx.searchAdapter missing — mount a search adapter to run this job.",
+    });
+  }
+  // perTenant fan-out — the job-runner enqueues one child run per active
+  // tenant with _tenantId set; a run without one (e.g. misconfigured
+  // manual dispatch outside the fan-out) has nothing scoped to reindex.
+  const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
+  if (tenantId === undefined) {
+    // skip: fired without a perTenant fan-out tenant — nothing scoped to reindex
+    return;
+  }
+  const db = ctx.db as DbConnection; // @cast-boundary db-operator
+  const result = await reindexEntity(db, ctx.registry, ctx.searchAdapter, entity, tenantId);
+  ctx.log?.info?.(
+    `[jobs:reindex-entity] tenant=${tenantId} reindexed ${entity}: ${result.indexedRows}/${result.scannedRows} rows indexed` +
+      `${result.failures.length > 0 ? ` (${result.failures.length} failed)` : ""}`,
+  );
+};

package/src/jobs/job-run-table.ts

@@ -48,7 +48,7 @@ export const jobRunEntity = createEntity({
     attempt: createNumberField({ required: true, default: 1, integer: true }),
     startedAt: createTimestampField({ required: true }),
     finishedAt: createTimestampField(),
-    duration: createNumberField(),
+    duration: createNumberField({ integer: true }),
     triggeredById: createTextField(),
   },
 });
@@ -60,7 +60,7 @@ export const jobRunsTable = buildEntityTable("job-run", jobRunEntity);
 // uuid of the parent jobRun. Existing detail-query callers treat it as an
 // opaque identifier, so the type-switch is backward-compatible at the
 // query surface.
-export const jobRunLogsTable = pgTable("read_job_run_logs", {
+export const jobRunLogsTable = pgTable("store_job_run_logs", {
   id: serial("id").primaryKey(),
   runId: text("run_id").notNull(),
   level: text("level").notNull().$type<JobLogLevel>(),
@@ -76,7 +76,7 @@ export const jobRunLogsTable = pgTable("read_job_run_logs", {
 // pgTable bleibt source-of-truth für Query-API; Phase 4 leitet das pgTable
 // aus dieser Meta ab.
 export const jobRunLogsTableMeta: EntityTableMeta = defineUnmanagedTable({
-  tableName: "read_job_run_logs",
+  tableName: "store_job_run_logs",
   columns: [
     { name: "id", pgType: "serial", notNull: true, primaryKey: true },
     { name: "run_id", pgType: "text", notNull: true },

package/src/personal-access-tokens/feature.ts

@@ -40,7 +40,7 @@ export function createPersonalAccessTokensFeature(
   const { scopes } = options;
   return defineFeature(PAT_FEATURE, (r) => {
     r.describe(
-      "Long-lived, revocable Personal Access Tokens for headless HTTP-API access. Stores SHA-256 token hashes in the `read_api_tokens` direct-write table; the plaintext is returned once at creation. `create`/`revoke`/`mine` manage a user's own tokens and `available-scopes` lists the app-declared scope catalog. Bearer tokens carrying the PAT prefix are resolved before jwt.verify (roles resolved live, granted scopes enforced fail-closed at the API boundary) — the resolver is wired via run-prod-app, not the dispatcher. Pass { toggleable: { default: false } } to tier-gate the whole feature.",
+      "Long-lived, revocable Personal Access Tokens for headless HTTP-API access. Stores SHA-256 token hashes in the `store_api_tokens` direct-write table; the plaintext is returned once at creation. `create`/`revoke`/`mine` manage a user's own tokens and `available-scopes` lists the app-declared scope catalog. Bearer tokens carrying the PAT prefix are resolved before jwt.verify (roles resolved live, granted scopes enforced fail-closed at the API boundary) — the resolver is wired via run-prod-app, not the dispatcher. Pass { toggleable: { default: false } } to tier-gate the whole feature.",
     );
     r.uiHints({ displayLabel: "Personal Access Tokens", category: "identity", recommended: false });
     // Opt-in tier-gating (mirrors ledger/tags): when set, the feature declares
@@ -50,10 +50,10 @@ export function createPersonalAccessTokensFeature(
     // Resolver reads memberships + users on every PAT request to build live
     // roles — make both boot-time deps so a mis-wiring fails validateBoot.
     r.requires("user", "tenant");
-    // Direct-write store like read_user_sessions: create/revoke write it, the
+    // Direct-write store like store_user_sessions: create/revoke write it, the
     // resolver point-reads it. r.entity would make it a rebuildable projection
     // whose replay (no token events) would wipe every live token (#498/#494).
-    r.rawTable(buildEntityTableMeta("api-token", apiTokenEntity), {
+    r.storeTable(buildEntityTableMeta("api-token", apiTokenEntity, { source: "unmanaged" }), {
       reason: "read_side.api_tokens_direct_write",
       // create.write encrypts `name` via encryptForDirectWrite (#820).
       piiEncryptedOnWrite: true,

package/src/personal-access-tokens/schema/api-token.ts

@@ -6,7 +6,7 @@ import {
   createTimestampField,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-// One row per Personal Access Token. Like read_user_sessions this is a
+// One row per Personal Access Token. Like store_user_sessions this is a
 // direct-write store (r.unmanagedTable): the create/revoke handlers write it and
 // the resolver point-reads it on the hot auth path. `tokenHash` is the SHA-256
 // of the plaintext (never the plaintext); the unique index on it makes the
@@ -14,7 +14,7 @@ import {
 // request can forge ownership/scope/hash by poking a field directly — the
 // handlers mutate them via ctx.db inside the pipeline.
 export const apiTokenEntity = createEntity({
-  table: "read_api_tokens",
+  table: "store_api_tokens",
   // No softDelete: revocation is its own lifecycle (revokedAt timestamp), and
   // we keep revoked rows for the "your tokens" audit list.
   softDelete: false,
@@ -52,10 +52,12 @@ export const apiTokenEntity = createEntity({
     expiresAt: createTimestampField({ access: { write: access.privileged } }),
     revokedAt: createTimestampField({ access: { write: access.privileged } }),
   },
-  indexes: [{ unique: true, columns: ["tokenHash"], name: "read_api_tokens_hash_unique" }],
+  indexes: [{ unique: true, columns: ["tokenHash"], name: "store_api_tokens_hash_unique" }],
 });
 
 // buildEntityTableMeta (not buildEntityTable): this is a direct-write store, so
 // the table must be a WritableTable (post ES-write-brand #742) — same as
 // sessions' userSessionTable. buildEntityTable is branded executor-only.
-export const apiTokenTable = buildEntityTableMeta("api-token", apiTokenEntity);
+export const apiTokenTable = buildEntityTableMeta("api-token", apiTokenEntity, {
+  source: "unmanaged",
+});

package/src/secrets/__tests__/rotate.integration.test.ts

@@ -175,8 +175,16 @@ describe("rotate-job circuit-breaker", () => {
   // Happy-path counterpart to the failure tests above: a working provider
   // that actually rewraps. Run last — it's the only test that mutates the
   // shared 20-row fixture, so the earlier "stays at 20" assertions must
-  // see it before this runs.
+  // see it before this runs. Enforced below, not just documented: a
+  // precondition check fails loud (not silently-wrong) if a test inserted
+  // between this and the circuit-breaker tests already touched the
+  // fixture — rotateJob's batch scan has no per-row exclusion/ordering
+  // to fall back on, so isolating this test onto a second tenant doesn't
+  // help (rotator would just exhaust maxFailures on the other tenant's
+  // still-V1 rows before ever reaching its own).
   test("successful rotation rewraps the DEK, bumps kekVersion, and preserves plaintext", async () => {
+    expect(await countV1Rows()).toBe(20);
+
     const rotator = createEnvMasterKeyProvider({
       env: {
         KUMIKO_SECRETS_MASTER_KEY_V1: SEED_V1_KEY,
@@ -185,6 +193,17 @@ describe("rotate-job circuit-breaker", () => {
       },
     });
 
+    // Snapshot pre-rotation ciphertext — rotate.job.ts's header comment
+    // claims "the ciphertext itself never changes, only the DEK wrapper".
+    // Assert that invariant below instead of only checking kekVersion/
+    // plaintext, which a rewrap-that-re-encrypts would also satisfy.
+    const preRotation = await selectMany<{ key: string; envelope: StoredEnvelope }>(
+      stack.db,
+      tenantSecretsTable,
+      { tenantId: admin.tenantId },
+    );
+    const ciphertextByKey = new Map(preRotation.map((row) => [row.key, row.envelope.ciphertext]));
+
     await rotateJob({ batchSize: 10, maxFailures: 5 }, jobCtx(rotator));
 
     expect(await countV1Rows()).toBe(0);
@@ -209,6 +228,9 @@ describe("rotate-job circuit-breaker", () => {
     expect(rows).toHaveLength(20);
     for (const row of rows) {
       expect(row.kekVersion).toBe(2);
+      const expectedCiphertext = ciphertextByKey.get(row.key);
+      expect(expectedCiphertext).toBeDefined();
+      expect(row.envelope.ciphertext).toBe(expectedCiphertext as string);
       const expectedIndex = row.key.split("-").at(-1);
       const plaintext = await decryptValue(decodeStoredEnvelope(row.envelope), verifier);
       expect(plaintext).toBe(`secret-${expectedIndex}`);

package/src/sessions/__tests__/rebuild-survival.integration.test.ts

@@ -19,7 +19,7 @@ import { createUserFeature } from "../../user/feature";
 import { createSessionsFeature } from "../feature";
 import { userSessionEntity, userSessionTable } from "../schema/user-session";
 
-// read_user_sessions is a hot-path direct-write store: sessionCreator inserts
+// store_user_sessions is a hot-path direct-write store: sessionCreator inserts
 // rows and the revoke handlers update them WITHOUT emitting lifecycle events.
 // If the table is registered as an r.entity, the framework makes it a
 // rebuildable implicit projection whose replay finds zero matching events and
@@ -27,7 +27,7 @@ import { userSessionEntity, userSessionTable } from "../schema/user-session";
 // session on the next projection rebuild (deploy / `schema apply`). #498/#494.
 //
 // Pre-fix both tests are RED: the implicit projection "sessions:projection:
-// user-session-entity" exists and rebuilding it empties read_user_sessions.
+// user-session-entity" exists and rebuilding it empties store_user_sessions.
 // Post-fix (r.unmanagedTable) the table is no longer a rebuild target.
 
 const IMPLICIT_PROJECTION = "sessions:projection:user-session-entity";
@@ -48,7 +48,7 @@ afterAll(async () => {
 
 beforeEach(async () => {
   await asRawClient(testDb.db).unsafe(
-    "TRUNCATE read_user_sessions, kumiko_events, kumiko_projections RESTART IDENTITY CASCADE",
+    "TRUNCATE store_user_sessions, kumiko_events, kumiko_projections RESTART IDENTITY CASCADE",
   );
 });
 
@@ -70,7 +70,7 @@ async function insertRevokedSession(db: DbConnection): Promise<void> {
   await updateRows(db, userSessionTable, { revokedAt: now }, { id: SID, revokedAt: null });
 }
 
-describe("sessions / read_user_sessions survives projection rebuild", () => {
+describe("sessions / store_user_sessions survives projection rebuild", () => {
   test("is NOT registered as a rebuildable implicit projection", () => {
     const registry = createRegistry([createSessionsFeature(), createUserFeature()]);
     expect(registry.getAllProjections().has(IMPLICIT_PROJECTION)).toBe(false);

package/src/sessions/db/queries/cleanup.ts

@@ -7,9 +7,9 @@ export async function deleteStaleSessionsBatch(
   batchSize: number,
 ): Promise<number> {
   const rows = (await asRawClient(db).unsafe(
-    `DELETE FROM "read_user_sessions"
+    `DELETE FROM "store_user_sessions"
      WHERE "id" IN (
-       SELECT "id" FROM "read_user_sessions"
+       SELECT "id" FROM "store_user_sessions"
        WHERE "expires_at" < now() - ($1::int * interval '1 day')
           OR "revoked_at" < now() - ($1::int * interval '1 day')
        LIMIT $2

package/src/sessions/feature.ts

@@ -58,7 +58,7 @@ export function bindAutoRevokeFromFeature(
   return undefined;
 }
 
-// The sessions feature registers the read_user_sessions table (as an
+// The sessions feature registers the store_user_sessions table (as an
 // unmanaged direct-write store, NOT an r.entity — see below) and the three
 // user-facing handlers (mine/revoke/revoke-all-others). It intentionally does NOT
 // export a sessionCreator/sessionRevoker here — those are produced by
@@ -76,7 +76,7 @@ export function bindAutoRevokeFromFeature(
 export function createSessionsFeature(options?: SessionsFeatureOptions): FeatureDefinition {
   return defineFeature("sessions", (r) => {
     r.describe(
-      "Tracks signed-in clients in the `read_user_sessions` table (one row per JWT, keyed by the `sid`/`jti` claim) and exposes handlers for `mine` (list your sessions), `revoke`, and `revokeAllOthers`. Session creation and revocation on the hot auth path are handled by `createSessionCallbacks()`, wired into `buildServer({ auth: { ... } })` outside the dispatcher; the feature also ships a manual-trigger cleanup job for pruning expired rows and an optional `autoRevokeOnPasswordChange` hook that mass-revokes all sessions for a user whenever their `passwordHash` changes.",
+      "Tracks signed-in clients in the `store_user_sessions` table (one row per JWT, keyed by the `sid`/`jti` claim) and exposes handlers for `mine` (list your sessions), `revoke`, and `revokeAllOthers`. Session creation and revocation on the hot auth path are handled by `createSessionCallbacks()`, wired into `buildServer({ auth: { ... } })` outside the dispatcher; the feature also ships a manual-trigger cleanup job for pruning expired rows and an optional `autoRevokeOnPasswordChange` hook that mass-revokes all sessions for a user whenever their `passwordHash` changes.",
     );
     r.uiHints({
       displayLabel: "Sessions · Server-side Logout",
@@ -87,16 +87,16 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
     // gate for locked accounts) — make that a boot-time dependency so a
     // sessions-without-user wiring fails validateBoot instead of 500ing live.
     r.requires("user");
-    // read_user_sessions is a hot-path direct-write store: sessionCreator
+    // store_user_sessions is a hot-path direct-write store: sessionCreator
     // inserts and the revoke handlers update rows WITHOUT emitting lifecycle
     // events (the row columns ARE the audit trail). Registering it as
     // r.entity would make it a rebuildable implicit projection whose replay
     // finds zero session events and swaps an empty shadow over the live
     // table — wiping every active session on the next projection rebuild
-    // (#498/#494). r.rawTable keeps the migration DDL but opts the
+    // (#498/#494). r.storeTable keeps the migration DDL but opts the
     // table out of implicit rebuild, like jobs/channel-in-app/feature-toggles
     // which are direct-write stores too.
-    r.rawTable(buildEntityTableMeta("user-session", userSessionEntity), {
+    r.storeTable(buildEntityTableMeta("user-session", userSessionEntity, { source: "unmanaged" }), {
       reason: "read_side.user_sessions_direct_write",
       // sessionCreator encrypts ip/userAgent via encryptForDirectWrite (#820).
       piiEncryptedOnWrite: true,

package/src/sessions/schema/user-session.ts

@@ -20,7 +20,7 @@ export const userSessionEntity = createEntity({
   // Entity-Key ist "user-session" (mit Dash), toTableName's snake-case-
   // Transform käme auf "read_user-sessions" → kein valides SQL ohne Quoting.
   // Deshalb expliziter Override auf den read_-konformen Namen.
-  table: "read_user_sessions",
+  table: "store_user_sessions",
   // sid-as-PK: the sessionCreator callback generates the UUID, returns it to
   // the framework; the framework stamps it as `jti`; here the same value is
   // the row primary key. Single source of truth for the identifier.
@@ -74,4 +74,6 @@ export const userSessionEntity = createEntity({
 // handlers write it directly via ctx.db; the meta carries no executor-only
 // brand so those writes stay legal. See feature.ts for the rebuild-exclusion
 // rationale (#494/#498).
-export const userSessionTable = buildEntityTableMeta("user-session", userSessionEntity);
+export const userSessionTable = buildEntityTableMeta("user-session", userSessionEntity, {
+  source: "unmanaged",
+});

package/src/tenant-lifecycle/stages.ts

@@ -109,7 +109,7 @@ async function tombstoneTenantRow(ctx: DestructionStageCtx): Promise<void> {
   const db = createTenantDb(ctx.db, ctx.tenantId, "system");
   // Per-row forget() through the executor, not a bulk deleteMany: memberships
   // are an ES-managed projection (add/remove/update-roles all go through
-  // tenantMembershipCrud), so a raw table write here is eventless — a future
+  // tenantMembershipCrud), so a store table write here is eventless — a future
   // projection rebuild would replay the historical add-member events and
   // resurrect rows this stage removed. forget() (Art.17 hard-purge) keeps the
   // erasure rebuild-safe and gives each membership its own audit event.

package/src/user-data-rights-defaults/__tests__/bundled-entities.userdata-hooks.integration.test.ts

@@ -146,7 +146,7 @@ async function seedUser(id: string): Promise<void> {
 describe("user-session userData-hooks", () => {
   async function seedSession(id: string, userId: string, tenantId: string): Promise<void> {
     await asRawClient(full.db).unsafe(
-      `INSERT INTO read_user_sessions (id, user_id, tenant_id, created_at, expires_at, ip, user_agent)
+      `INSERT INTO store_user_sessions (id, user_id, tenant_id, created_at, expires_at, ip, user_agent)
        VALUES ($1, $2, $3, now(), now() + interval '1 day', '203.0.113.7', 'TestAgent/1.0')`,
       [id, userId, tenantId],
     );
@@ -170,11 +170,11 @@ describe("user-session userData-hooks", () => {
     await userSessionDeleteHook(ctx("sess-user-2"), "delete");
 
     const a = await rawSelect(
-      "SELECT * FROM read_user_sessions WHERE user_id = $1 AND tenant_id = $2",
+      "SELECT * FROM store_user_sessions WHERE user_id = $1 AND tenant_id = $2",
       ["sess-user-2", TENANT_A],
     );
     const b = await rawSelect(
-      "SELECT * FROM read_user_sessions WHERE user_id = $1 AND tenant_id = $2",
+      "SELECT * FROM store_user_sessions WHERE user_id = $1 AND tenant_id = $2",
       ["sess-user-2", TENANT_B],
     );
     expect(a).toHaveLength(0);
@@ -185,7 +185,7 @@ describe("user-session userData-hooks", () => {
 describe("api-token userData-hooks", () => {
   async function seedToken(id: string, userId: string): Promise<void> {
     await asRawClient(full.db).unsafe(
-      `INSERT INTO read_api_tokens (id, user_id, tenant_id, name, token_hash, prefix, scopes, created_at)
+      `INSERT INTO store_api_tokens (id, user_id, tenant_id, name, token_hash, prefix, scopes, created_at)
        VALUES ($1, $2, $3, 'My MacBook', $4, 'kum_ab12', '["read"]', now())`,
       [id, userId, TENANT_A, `hash-${id}`],
     );
@@ -207,7 +207,7 @@ describe("api-token userData-hooks", () => {
 
     await apiTokenDeleteHook(ctx("pat-user-2"), "delete");
 
-    const rows = await rawSelect("SELECT * FROM read_api_tokens WHERE user_id = $1", [
+    const rows = await rawSelect("SELECT * FROM store_api_tokens WHERE user_id = $1", [
       "pat-user-2",
     ]);
     expect(rows).toHaveLength(0);
@@ -371,7 +371,7 @@ describe("config-value userData-hooks", () => {
 describe("delivery-attempt userData-hooks (#799)", () => {
   async function seedAttempt(id: string, recipientId: string, tenantId: string): Promise<void> {
     await asRawClient(full.db).unsafe(
-      `INSERT INTO read_delivery_attempts
+      `INSERT INTO store_delivery_attempts
          (id, tenant_id, notification_type, channel, recipient_id, recipient_address, status, priority)
        VALUES ($1, $2, 'app:notify:ping', 'email', $3, $4, 'sent', 'normal')`,
       [id, tenantId, recipientId, `user-${recipientId}@example.com`],