@cosmicdrift/kumiko-framework 0.320.0 → 0.322.0

package/src/event-store/__tests__/transfer.integration.test.ts

@@ -0,0 +1,236 @@
+// transferAggregateStreams — the event store's own tenant-transfer primitive.
+// Pins: events, snapshots and the archive marker all move together; a system
+// aggregate.transferred event lands per moved aggregate; an empty id list is
+// a no-op; an id with no events under the given tenant/aggregateType is left
+// untouched; an aggregate belonging to an unrelated third tenant is never
+// touched by another tenant's move; an archive marker for a DIFFERENT
+// aggregate type sharing the same aggregate id stays behind.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { asRawClient } from "../../db/query";
+import type { TenantId } from "../../engine/types";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import { generateId as uuid } from "../../utils";
+import {
+  AGGREGATE_TRANSFER_STREAM_TYPE,
+  AGGREGATE_TRANSFERRED_EVENT_TYPE,
+  append,
+  archiveStream,
+  isStreamArchived,
+  loadAggregate,
+  loadLatestSnapshot,
+  saveSnapshot,
+  transferAggregateStreams,
+} from "../index";
+
+let bun: BunTestDb;
+const sourceTenant = uuid() as TenantId;
+const destinationTenant = uuid() as TenantId;
+const otherTenant = uuid() as TenantId;
+const userId = uuid();
+const transferredBy = uuid();
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  bun = await createTestDb();
+});
+
+afterAll(async () => {
+  await bun.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(bun.db).unsafe(
+    `TRUNCATE kumiko_events, kumiko_snapshots, kumiko_archived_streams RESTART IDENTITY`,
+  );
+});
+
+async function seedAggregate(tenantId: TenantId, aggregateType = "counter"): Promise<string> {
+  const aggregateId = uuid();
+  await append(bun.db, {
+    aggregateId,
+    aggregateType,
+    tenantId,
+    expectedVersion: 0,
+    type: "counter.incremented",
+    payload: { by: 1 },
+    metadata: { userId },
+  });
+  return aggregateId;
+}
+
+// Each `aggregate.transferred` event lives on its OWN fresh stream (see
+// transfer.ts) — the row's own `aggregate_id` column is that stream's id,
+// not the moved aggregate's. The moved aggregate's id is in the payload.
+async function transferredEvents(tenantId: TenantId): Promise<readonly Record<string, unknown>[]> {
+  const rows = (await asRawClient(bun.db).unsafe(
+    `SELECT payload FROM kumiko_events WHERE tenant_id = $1 AND aggregate_type = $2 AND type = $3`,
+    [tenantId, AGGREGATE_TRANSFER_STREAM_TYPE, AGGREGATE_TRANSFERRED_EVENT_TYPE],
+  )) as ReadonlyArray<{ payload: Record<string, unknown> }>;
+  return rows.map((row) => row.payload);
+}
+
+describe("transferAggregateStreams", () => {
+  test("moves events, drops the snapshot, carries the archive marker, and emits one aggregate.transferred event per moved aggregate", async () => {
+    const first = await seedAggregate(sourceTenant);
+    const second = await seedAggregate(sourceTenant);
+    await saveSnapshot(bun.db, {
+      aggregateId: first,
+      tenantId: sourceTenant,
+      aggregateType: "counter",
+      version: 1,
+      state: { count: 1 },
+    });
+    await archiveStream(bun.db, {
+      tenantId: sourceTenant,
+      aggregateId: first,
+      aggregateType: "counter",
+      archivedBy: "ops",
+    });
+
+    const movedCount = await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [first, second],
+      transferredBy,
+    });
+    expect(movedCount).toBe(2);
+
+    // Events: gone from the source tenant, present under the destination.
+    expect(
+      await loadAggregate(bun.db, first, sourceTenant, { includeArchived: true }),
+    ).toHaveLength(0);
+    expect(await loadAggregate(bun.db, second, sourceTenant)).toHaveLength(0);
+    const firstEvents = await loadAggregate(bun.db, first, destinationTenant, {
+      includeArchived: true,
+    });
+    expect(firstEvents.some((e) => e.type === "counter.incremented")).toBe(true);
+    const secondEvents = await loadAggregate(bun.db, second, destinationTenant);
+    expect(secondEvents.some((e) => e.type === "counter.incremented")).toBe(true);
+
+    // Snapshot dropped from the source tenant, not recreated anywhere.
+    expect(await loadLatestSnapshot(bun.db, first, sourceTenant)).toBeNull();
+    expect(await loadLatestSnapshot(bun.db, first, destinationTenant)).toBeNull();
+
+    // Archive marker moved with the stream.
+    expect(await isStreamArchived(bun.db, sourceTenant, first)).toBe(false);
+    expect(await isStreamArchived(bun.db, destinationTenant, first)).toBe(true);
+    expect(await isStreamArchived(bun.db, destinationTenant, second)).toBe(false);
+
+    // One system event per moved aggregate, in the destination tenant.
+    const events = await transferredEvents(destinationTenant);
+    expect(events).toHaveLength(2);
+    const byAggregateId = new Map(events.map((payload) => [payload["aggregateId"], payload]));
+    expect(byAggregateId.get(first)).toMatchObject({
+      aggregateType: "counter",
+      aggregateId: first,
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+    });
+    expect(byAggregateId.get(second)).toMatchObject({
+      aggregateType: "counter",
+      aggregateId: second,
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+    });
+  });
+
+  test("an empty id list is a no-op", async () => {
+    const movedCount = await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [],
+      transferredBy,
+    });
+    expect(movedCount).toBe(0);
+    expect(await transferredEvents(destinationTenant)).toHaveLength(0);
+  });
+
+  test("an id with no events under this tenant/aggregateType is left untouched and gets no event", async () => {
+    const untouched = uuid();
+    const movedCount = await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [untouched],
+      transferredBy,
+    });
+    expect(movedCount).toBe(0);
+    expect(await loadAggregate(bun.db, untouched, sourceTenant)).toHaveLength(0);
+    expect(await loadAggregate(bun.db, untouched, destinationTenant)).toHaveLength(0);
+    expect(await transferredEvents(destinationTenant)).toHaveLength(0);
+  });
+
+  test("an aggregate under an unrelated third tenant with the same id is untouched", async () => {
+    const sharedId = uuid();
+    await append(bun.db, {
+      aggregateId: sharedId,
+      aggregateType: "counter",
+      tenantId: otherTenant,
+      expectedVersion: 0,
+      type: "counter.incremented",
+      payload: { by: 1 },
+      metadata: { userId },
+    });
+    await append(bun.db, {
+      aggregateId: sharedId,
+      aggregateType: "counter",
+      tenantId: sourceTenant,
+      expectedVersion: 0,
+      type: "counter.incremented",
+      payload: { by: 1 },
+      metadata: { userId },
+    });
+
+    await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [sharedId],
+      transferredBy,
+    });
+
+    const otherTenantEvents = await loadAggregate(bun.db, sharedId, otherTenant);
+    expect(otherTenantEvents).toHaveLength(1);
+    expect(await loadAggregate(bun.db, sharedId, sourceTenant)).toHaveLength(0);
+  });
+
+  test("an archived marker for a different aggregate type sharing the moved aggregate's id stays in the source tenant", async () => {
+    const sharedId = uuid();
+    // `append()` shares its version-conflict check across the plain
+    // aggregateId, so a real "widget" stream can't coexist with a real
+    // "counter" stream under the same id/tenant — fabricate the archived
+    // marker directly (the primary verifier of the event-store primitive,
+    // same reasoning as guard-event-store-writes' own __tests__ exclusion)
+    // to prove the WHERE clause's aggregate_type filter, not the stream's
+    // version-numbering.
+    await asRawClient(bun.db).unsafe(
+      `INSERT INTO "kumiko_archived_streams" ("tenant_id", "aggregate_id", "aggregate_type", "archived_by") VALUES ($1, $2, $3, $4)`,
+      [sourceTenant, sharedId, "widget", "ops"],
+    );
+    await append(bun.db, {
+      aggregateId: sharedId,
+      aggregateType: "counter",
+      tenantId: sourceTenant,
+      expectedVersion: 0,
+      type: "counter.incremented",
+      payload: { by: 1 },
+      metadata: { userId },
+    });
+
+    const movedCount = await transferAggregateStreams(bun.db, {
+      sourceTenantId: sourceTenant,
+      destinationTenantId: destinationTenant,
+      aggregateType: "counter",
+      aggregateIds: [sharedId],
+      transferredBy,
+    });
+    expect(movedCount).toBe(1);
+
+    expect(await isStreamArchived(bun.db, sourceTenant, sharedId)).toBe(true);
+    expect(await isStreamArchived(bun.db, destinationTenant, sharedId)).toBe(false);
+  });
+});

package/src/event-store/index.ts

@@ -53,6 +53,12 @@ export {
   saveSnapshot,
   snapshotsTable,
 } from "./snapshot";
+export {
+  AGGREGATE_TRANSFER_STREAM_TYPE,
+  AGGREGATE_TRANSFERRED_EVENT_TYPE,
+  type TransferAggregateStreamsArgs,
+  transferAggregateStreams,
+} from "./transfer";
 export {
   type EventUpcasters,
   makeUpcastCtx,

package/src/event-store/transfer.ts

@@ -0,0 +1,84 @@
+// The event store's own tenant-transfer primitive: the ONE place allowed to
+// move a stream across the tenant boundary (enforced by
+// guard-event-store-writes' allowlist). Each move leaves an audit event in
+// the destination tenant.
+//
+// Runs entirely on the caller-supplied DbRunner, so the move rides whatever
+// transaction the caller is already inside (tenant-handover's claim handler
+// commits it together with the root row's ownership write — see
+// move-entity-graph.ts's file header for why that matters).
+
+import type { DbRunner } from "../db";
+import {
+  deleteSnapshotsForAggregates,
+  transferArchivedStreamRows,
+  transferEventRows,
+} from "../db/queries/event-store-transfer";
+import type { TenantId } from "../engine/types";
+import { SYSTEM_EVENT_PREFIX } from "../pipeline/append-event-core";
+import { generateId } from "../utils/ids";
+import { append } from "./event-store";
+
+export const AGGREGATE_TRANSFER_STREAM_TYPE = "aggregate-transfer";
+export const AGGREGATE_TRANSFERRED_EVENT_TYPE = `${SYSTEM_EVENT_PREFIX}aggregate.transferred`;
+
+export type TransferAggregateStreamsArgs = {
+  readonly sourceTenantId: TenantId;
+  readonly destinationTenantId: TenantId;
+  readonly aggregateType: string;
+  readonly aggregateIds: readonly string[];
+  readonly transferredBy: string;
+};
+
+// Moves one aggregate type's event history, drops its cached snapshots, and
+// carries any archive marker across the tenant boundary. Returns the number
+// of aggregates that actually had events (and therefore moved) — an id in
+// `aggregateIds` with no events under `sourceTenantId`/`aggregateType`
+// contributes nothing and gets no follow-up event.
+export async function transferAggregateStreams(
+  db: DbRunner,
+  args: TransferAggregateStreamsArgs,
+): Promise<number> {
+  if (args.aggregateIds.length === 0) return 0;
+
+  const movedAggregateIds = await transferEventRows(db, {
+    sourceTenantId: args.sourceTenantId,
+    destinationTenantId: args.destinationTenantId,
+    aggregateType: args.aggregateType,
+    aggregateIds: args.aggregateIds,
+  });
+  if (movedAggregateIds.length === 0) return 0;
+
+  await deleteSnapshotsForAggregates(db, {
+    tenantId: args.sourceTenantId,
+    aggregateIds: movedAggregateIds,
+  });
+  await transferArchivedStreamRows(db, {
+    sourceTenantId: args.sourceTenantId,
+    destinationTenantId: args.destinationTenantId,
+    aggregateType: args.aggregateType,
+    aggregateIds: movedAggregateIds,
+  });
+
+  for (const aggregateId of movedAggregateIds) {
+    // A fresh, own stream — not an append onto the moved aggregate's own
+    // stream — so the marker never bumps the moved aggregate's version or
+    // shows up when a projection replays that aggregate's history.
+    await append(db, {
+      aggregateId: generateId(),
+      aggregateType: AGGREGATE_TRANSFER_STREAM_TYPE,
+      tenantId: args.destinationTenantId,
+      expectedVersion: 0,
+      type: AGGREGATE_TRANSFERRED_EVENT_TYPE,
+      payload: {
+        aggregateType: args.aggregateType,
+        aggregateId,
+        sourceTenantId: args.sourceTenantId,
+        destinationTenantId: args.destinationTenantId,
+      },
+      metadata: { userId: args.transferredBy },
+    });
+  }
+
+  return movedAggregateIds.length;
+}

package/src/i18n/__tests__/i18n.test.ts

@@ -76,3 +76,38 @@ describe("createI18n", () => {
     expect(keys).toContain("adminUsers:field.email");
   });
 });
+
+describe("createI18n — plural forms", () => {
+  const notificationsFeature = defineFeature("notifications", (r) => {
+    r.translations({
+      keys: {
+        "notifications.unread": {
+          de: { one: "{count} ungelesene Nachricht", other: "{count} ungelesene Nachrichten" },
+          en: { one: "{count} unread message", other: "{count} unread messages" },
+        },
+      },
+    });
+  });
+
+  test("resolves the CLDR category for the given locale and count", () => {
+    const registry = createRegistry([notificationsFeature]);
+    const i18n = createI18n(registry, { defaultLocale: "en" });
+
+    expect(i18n.t("notifications:notifications.unread", "en", { count: 1 })).toBe(
+      "1 unread message",
+    );
+    expect(i18n.t("notifications:notifications.unread", "en", { count: 5 })).toBe(
+      "5 unread messages",
+    );
+    expect(i18n.t("notifications:notifications.unread", "de", { count: 1 })).toBe(
+      "1 ungelesene Nachricht",
+    );
+  });
+
+  test("falls back to `other` when no params are given", () => {
+    const registry = createRegistry([notificationsFeature]);
+    const i18n = createI18n(registry, { defaultLocale: "en" });
+
+    expect(i18n.t("notifications:notifications.unread", "en")).toBe("{count} unread messages");
+  });
+});

package/src/i18n/__tests__/mail-registry.test.ts

@@ -33,3 +33,22 @@ test("resolveMailLocale prefers exact, then root, then en", () => {
   expect(resolveMailLocale("de-AT")).toBe("de");
   expect(resolveMailLocale("fr-CA")).toBe("en");
 });
+
+describe("mailT — plural forms", () => {
+  registerMailTranslations("en", {
+    "test.unread": { one: "{count} unread message", other: "{count} unread messages" },
+  });
+  registerMailTranslations("de", {
+    "test.unread": { one: "{count} ungelesene Nachricht", other: "{count} ungelesene Nachrichten" },
+  });
+
+  test("resolves the CLDR category for the count", () => {
+    expect(mailT("en", "test.unread", { count: 1 })).toBe("1 unread message");
+    expect(mailT("en", "test.unread", { count: 5 })).toBe("5 unread messages");
+    expect(mailT("de", "test.unread", { count: 1 })).toBe("1 ungelesene Nachricht");
+  });
+
+  test("uses the fallback locale's own plural rules, not the requested locale's", () => {
+    expect(mailT("fr", "test.unread", { count: 1 })).toBe("1 unread message");
+  });
+});

package/src/i18n/index.ts

@@ -1,4 +1,5 @@
 import type { Registry, TranslationKeys } from "../engine/types";
+import { resolveTranslationValue } from "../ui-types/plural";
 
 export {
   hasMailTranslations,
@@ -20,7 +21,7 @@ export type I18nOptions = {
 };
 
 export type I18n = {
-  t(key: string, locale?: string): string;
+  t(key: string, locale?: string, params?: Readonly<Record<string, unknown>>): string;
   getAllKeys(): string[];
 };
 
@@ -29,12 +30,18 @@ export function createI18n(registry: Registry, options: I18nOptions): I18n {
   const { defaultLocale } = options;
 
   return {
-    t(key: string, locale?: string): string {
+    t(key: string, locale?: string, params?: Readonly<Record<string, unknown>>): string {
       const entry = translations[key];
       if (!entry) return key;
 
-      const resolvedLocale = locale ?? defaultLocale;
-      return entry[resolvedLocale] ?? entry[defaultLocale] ?? key;
+      const requestedLocale = locale ?? defaultLocale;
+      // Plural category selection needs the locale the value actually came
+      // from, not the requested one — falling back to defaultLocale must
+      // apply defaultLocale's plural rules to that defaultLocale text.
+      const hitLocale = entry[requestedLocale] !== undefined ? requestedLocale : defaultLocale;
+      const value = entry[hitLocale];
+      if (value === undefined) return key;
+      return resolveTranslationValue(value, hitLocale, params);
     },
 
     getAllKeys(): string[] {

package/src/i18n/mail-registry.ts

@@ -1,8 +1,10 @@
-const tables = new Map<string, Readonly<Record<string, string>>>();
+import { resolveTranslationValue, type TranslationValue } from "../ui-types/plural";
+
+const tables = new Map<string, Readonly<Record<string, TranslationValue>>>();
 
 export function registerMailTranslations(
   locale: string,
-  bundle: Readonly<Record<string, string>>,
+  bundle: Readonly<Record<string, TranslationValue>>,
 ): void {
   const prev = tables.get(locale) ?? {};
   tables.set(locale, { ...prev, ...bundle });
@@ -16,13 +18,17 @@ export function hasMailTranslations(locale: string): boolean {
 export function mailT(
   locale: string,
   key: string,
-  params?: Readonly<Record<string, string>>,
+  params?: Readonly<Record<string, string | number>>,
 ): string {
   const root = locale.split("-")[0] ?? locale;
-  const raw =
-    tables.get(locale)?.[key] ?? tables.get(root)?.[key] ?? tables.get("en")?.[key] ?? key;
-  if (params === undefined) return raw;
-  return raw.replace(/\{(\w+)\}/g, (_, name: string) => params[name] ?? `{${name}}`);
+  // Plural category selection needs the locale the value actually came
+  // from, not the requested one — a `pl` bundle falling back to `en`
+  // must apply English plural rules to that `en` text.
+  for (const localeToTry of [locale, root, "en"]) {
+    const value = tables.get(localeToTry)?.[key];
+    if (value !== undefined) return resolveTranslationValue(value, localeToTry, params);
+  }
+  return key;
 }
 
 /** Locale key mailT would actually use (exact → root → en). Use for appUrl

package/src/pipeline/__tests__/archive-stream.integration.test.ts

@@ -102,7 +102,9 @@ const archFeature = defineFeature("archtest", (r) => {
     "item:delete",
     z.object({ id: z.uuid() }),
     async (event, ctx) => executor.delete({ id: event.payload.id }, event.user, ctx.db),
-    { access: { roles: ["Admin"] } },
+    // arch-item has no softDelete — a hard delete needs agent.risk: "high"
+    // to pass the irreversible-operation gate.
+    { access: { roles: ["Admin"] }, agent: { risk: "high" } },
   );
 
   r.queryHandler(