@cosmicdrift/kumiko-bundled-features 0.105.2 → 0.108.0

package/src/sessions/__tests__/sessions.integration.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomBytes } from "node:crypto";
-import { deleteMany, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEncryptionProvider } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
@@ -10,7 +10,12 @@ import {
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { createLateBoundHolder, resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
+import {
+  createLateBoundHolder,
+  deleteRows,
+  resetTestTables,
+  updateRows,
+} from "@cosmicdrift/kumiko-framework/testing";
 import { Temporal } from "temporal-polyfill";
 import { AuthHandlers } from "../../auth-email-password/constants";
 import { createAuthEmailPasswordFeature } from "../../auth-email-password/feature";
@@ -367,7 +372,7 @@ describe("sessions feature — login → check → revoke → rejected", () => {
 
     // Hard-delete the session row so it's gone from the store (as opposed to
     // soft-revoked). The JWT stays syntactically valid.
-    await deleteMany(stack.db, userSessionTable, { id: sid });
+    await deleteRows(stack.db, userSessionTable, { id: sid });
 
     const res = await h.authedPost("/api/query", token, {
       type: "user:query:user:me",
@@ -384,7 +389,7 @@ describe("sessions feature — login → check → revoke → rejected", () => {
 
     // Back-date expiresAt so the row is still present + not revoked, just
     // past its window. Simulates what a long-lived JWT would hit.
-    await updateMany(
+    await updateRows(
       stack.db,
       userSessionTable,
       { expiresAt: Temporal.Instant.from("2020-01-01T00:00:00Z") },
@@ -422,7 +427,7 @@ describe("sessions feature — login → check → revoke → rejected", () => {
     // so she gets a fresh JWT with the new role in its claims. This is the
     // actual production path — roles are tenant-membership data, not JWT
     // metadata we can fiddle with directly.
-    await updateMany(
+    await updateRows(
       stack.db,
       tenantMembershipsTable,
       { roles: JSON.stringify(["Admin"]) },
@@ -475,7 +480,7 @@ describe("sessions feature — locked accounts blocked on a live session", () =>
   test("restricted after login → 401 reason=blocked", async () => {
     const { userId } = await h.seedUser("restrict@example.com", "pw-long-enough");
     const { token } = await h.login("restrict@example.com", "pw-long-enough");
-    await updateMany(stack.db, userTable, { status: USER_STATUS.Restricted }, { id: userId });
+    await updateRows(stack.db, userTable, { status: USER_STATUS.Restricted }, { id: userId });
 
     const res = await h.authedPost("/api/query", token, {
       type: "user:query:user:me",
@@ -489,7 +494,7 @@ describe("sessions feature — locked accounts blocked on a live session", () =>
   test("deleted after login → 401 reason=blocked", async () => {
     const { userId } = await h.seedUser("gone@example.com", "pw-long-enough");
     const { token } = await h.login("gone@example.com", "pw-long-enough");
-    await updateMany(stack.db, userTable, { status: USER_STATUS.Deleted }, { id: userId });
+    await updateRows(stack.db, userTable, { status: USER_STATUS.Deleted }, { id: userId });
 
     const res = await h.authedPost("/api/query", token, {
       type: "user:query:user:me",
@@ -507,7 +512,7 @@ describe("sessions feature — locked accounts blocked on a live session", () =>
     // into a global lockout for every affected session instead of a no-op.
     const { userId } = await h.seedUser("hardgone@example.com", "pw-long-enough");
     const { token } = await h.login("hardgone@example.com", "pw-long-enough");
-    await deleteMany(stack.db, userTable, { id: userId });
+    await deleteRows(stack.db, userTable, { id: userId });
 
     const res = await h.authedPost("/api/query", token, {
       type: "user:query:user:me",
@@ -519,7 +524,7 @@ describe("sessions feature — locked accounts blocked on a live session", () =>
   test("deletionRequested keeps its session live — reversible grace period", async () => {
     const { userId } = await h.seedUser("leaving@example.com", "pw-long-enough");
     const { token } = await h.login("leaving@example.com", "pw-long-enough");
-    await updateMany(
+    await updateRows(
       stack.db,
       userTable,
       { status: USER_STATUS.DeletionRequested },

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

@@ -1,4 +1,4 @@
-import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+import { buildEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   createEntity,
@@ -64,4 +64,10 @@ export const userSessionEntity = createEntity({
   },
 });
 
-export const userSessionTable = buildEntityTable("user_session", userSessionEntity);
+// Plain EntityTableMeta, NOT a branded EntityTable: user-session is an
+// unmanaged direct-write store (r.unmanagedTable in feature.ts, no event
+// stream — revocation is a column write, not an aggregate). The feature's
+// 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);

package/src/sessions/session-callbacks.ts

@@ -10,14 +10,14 @@ import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "temporal-polyfill";
-import { USER_STATUS, userTable } from "../user";
+import { USER_STATUS, type UserStatus, userTable } from "../user";
 import { DEFAULT_SESSION_EXPIRY_MS } from "./constants";
 import { userSessionTable } from "./schema/user-session";
 
 // Locked accounts whose live sessions must be refused. deletionRequested is
 // intentionally absent — it's a reversible grace period and the user needs
 // their session to reach cancel-deletion.
-const BLOCKED_STATUSES: ReadonlySet<string> = new Set([
+const BLOCKED_STATUSES: ReadonlySet<UserStatus> = new Set([
   USER_STATUS.Restricted,
   USER_STATUS.Deleted,
 ]);
@@ -104,7 +104,13 @@ export function createSessionCallbacks(opts: SessionCallbacksOptions): SessionCa
       // a stale sid. Fail-OPEN on a lookup miss — this is the second layer,
       // revocation is primary; never turn a user-row miss into a global
       // lockout. (+1 PK read on read_users per authenticated request.)
-      const user = await fetchOne<{ status: string }>(db, userTable, { id: expectedUserId });
+      //
+      // Fail-open covers a THROW too, not just a null-miss: this read sits on
+      // the hot path of every authenticated request, so a DB timeout / lock
+      // contention / pool exhaustion here must not turn into a global lockout.
+      const user = await fetchOne<{ status: UserStatus }>(db, userTable, {
+        id: expectedUserId,
+      }).catch(() => null);
       if (user && BLOCKED_STATUSES.has(user.status)) return "blocked";
       return "live";
     },

package/src/subscription-stripe/__tests__/runtime.test.ts

@@ -44,34 +44,24 @@ const BILLING_LIVE_HANDLE: ConfigKeyHandle<"boolean"> = {
 
 /** Stub-SecretsContext: liest aus einer in-memory-map, matcht per
  *  qualified-name. backing:"secrets" persistiert config-Werte JSON-
- *  serialisiert — der Stub spiegelt das, damit der Runtime-parseStoredSecret
- *  denselben Pfad nimmt wie gegen den echten Store. Ignoriert auditCtx. */
-function stubSecrets(values: Record<string, string>): SecretsContext {
+ *  serialisiert — der Stub spiegelt das per Default, damit der Runtime-
+ *  parseStoredSecret denselben Pfad nimmt wie gegen den echten Store.
+ *  `raw: true` speichert UN-serialisiert (482/1) — um parseStoredSecret's
+ *  Fehlerpfad zu treffen: ein Credential, das der Store un-JSON-kodiert
+ *  zurückgibt (Korruption oder außerhalb des backing:"secrets"-Roundtrips
+ *  geschrieben) muss laut failen, nicht still Müll liefern. Ignoriert
+ *  auditCtx. */
+function stubSecrets(
+  values: Record<string, string>,
+  opts?: { readonly raw?: boolean },
+): SecretsContext {
   const nameOf = (k: string | { readonly name: string }): string =>
     typeof k === "string" ? k : k.name;
   return {
     get: async (_tenantId, key) => {
       const value = values[nameOf(key)];
-      return value === undefined ? undefined : createSecret(JSON.stringify(value));
-    },
-    has: async (_tenantId, key) => values[nameOf(key)] !== undefined,
-    set: async () => undefined,
-    delete: async () => false,
-  };
-}
-
-/** Wie stubSecrets, aber speichert den Wert ROH (kein JSON.stringify) — um
- *  parseStoredSecret's Fehlerpfad zu treffen: ein Credential, das der Store
- *  un-JSON-kodiert zurückgibt (Korruption oder ein außerhalb des
- *  backing:"secrets"-Roundtrips geschriebener Wert) muss laut failen, nicht
- *  still Müll liefern. */
-function rawSecretsStub(values: Record<string, string>): SecretsContext {
-  const nameOf = (k: string | { readonly name: string }): string =>
-    typeof k === "string" ? k : k.name;
-  return {
-    get: async (_tenantId, key) => {
-      const value = values[nameOf(key)];
-      return value === undefined ? undefined : createSecret(value); // RAW, not JSON
+      if (value === undefined) return undefined;
+      return createSecret(opts?.raw ? value : JSON.stringify(value));
     },
     has: async (_tenantId, key) => values[nameOf(key)] !== undefined,
     set: async () => undefined,
@@ -164,7 +154,7 @@ describe("StripeCtxRuntime.clientForCtx", () => {
     // throw, not silently fall through to undefined/fallback.
     const rt = makeRuntimes({ apiKey: "sk_test_fallback" });
     const ctx = stubCtx({
-      secrets: rawSecretsStub({ [API_KEY_HANDLE.name]: "sk_test_raw_unquoted" }),
+      secrets: stubSecrets({ [API_KEY_HANDLE.name]: "sk_test_raw_unquoted" }, { raw: true }),
     });
     await expect(rt.ctx.clientForCtx(ctx)).rejects.toThrow(
       /Invalid JSON in subscription-stripe credential/,

package/src/tags/__tests__/tags.integration.test.ts

@@ -306,6 +306,21 @@ describe("tags integration — idempotency", () => {
     expect(rows).toHaveLength(1);
     expect(rows[0]?.["tagId"]).toBe(tagId);
   });
+
+  test("two concurrent first-time assigns of the same (tag, entity) both succeed — one row", async () => {
+    // Both requests read `existing === null` before either write lands, so
+    // both fall through to create(); the loser's create() version_conflicts.
+    // The handler must converge that into success instead of surfacing a 409
+    // for what is, from the caller's perspective, an idempotent operation.
+    const tagId = await createTag("racy");
+    const [a, b] = await Promise.all([
+      assign(tagId, "credit", "credit-race"),
+      assign(tagId, "credit", "credit-race"),
+    ]);
+    expect(a).toBeDefined();
+    expect(b).toBeDefined();
+    expect(await countAssignments(admin.tenantId)).toBe(1);
+  });
 });
 
 describe("tags integration — referential integrity", () => {

package/src/tags/handlers/assign-tag.write.ts

@@ -14,8 +14,9 @@ import { type AssignTagPayload, assignTagPayloadSchema } from "../schemas";
 //     append at version 0 onto the created+deleted stream and version_conflict;
 //     the deterministic id means that stream is permanent.
 //   - never assigned         → create() (restore reports not_found).
-// A concurrent first-time race still version_conflicts (409); acceptable, since
-// assigning is a low-frequency UI action.
+// A concurrent first-time race converges: both callers fall through to
+// create(), the loser's create() version_conflicts, and the handler treats
+// that as success since the winner already wrote the desired end state.
 //
 // Referential integrity: there is no FK (event-sourced, no JOIN), so before a
 // first-time create we verify the tag exists in the catalog — a malformed call
@@ -46,7 +47,7 @@ export function createAssignTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS):
       const tag = await tagExecutor.detail({ id: payload.tagId }, event.user, ctx.db);
       if (!tag) return writeFailure(new NotFoundError("tag", payload.tagId));
 
-      return tagAssignmentExecutor.create(
+      const created = await tagAssignmentExecutor.create(
         {
           id,
           tagId: payload.tagId,
@@ -56,6 +57,15 @@ export function createAssignTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS):
         event.user,
         ctx.db,
       );
+      if (created.isSuccess) return created;
+      // A concurrent first-time assign of the same (tag, entity) races here —
+      // both callers' `existing` read above saw null, so both fall through to
+      // create(). The loser's create() version_conflicts (409), but the
+      // desired end state (the assignment exists) is already true — the
+      // winner just wrote it. Converge instead of surfacing a spurious 409
+      // for an idempotent operation.
+      if (created.error.code !== "version_conflict") return created;
+      return { isSuccess: true as const, data: { id } };
     },
   };
 }

package/src/tags/schemas.ts

@@ -1,8 +1,11 @@
 import { z } from "zod";
 
 export const createTagPayloadSchema = z.object({
-  name: z.string().min(1).max(64),
-  color: z.string().max(32).optional(),
+  name: z.string().trim().min(1).max(64),
+  color: z
+    .string()
+    .regex(/^(#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}))?$/, "color must be a hex code (#rgb or #rrggbb)")
+    .optional(),
   scope: z.string().max(64).optional(),
 });
 export type CreateTagPayload = z.infer<typeof createTagPayloadSchema>;
@@ -16,8 +19,11 @@ export const updateTagPayloadSchema = z
   .object({
     id: z.string().min(1),
     version: z.number().int().nonnegative(),
-    name: z.string().min(1).max(64).optional(),
-    color: z.string().max(32).optional(),
+    name: z.string().trim().min(1).max(64).optional(),
+    color: z
+      .string()
+      .regex(/^(#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}))?$/, "color must be a hex code (#rgb or #rrggbb)")
+      .optional(),
     scope: z.string().max(64).optional(),
   })
   .refine((p) => p.name !== undefined || p.color !== undefined || p.scope !== undefined, {

package/src/template-resolver/__tests__/template-resolver.integration.test.ts

@@ -1,11 +1,11 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   setupTestStack,
   type TestStack,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import { createTemplateResolverApi, TemplateNotFoundError, type TemplateResolverApi } from "../api";
 import {
   type ContentFormat,
@@ -56,7 +56,7 @@ async function seedTemplate(args: {
   linkedResources?: Record<string, string>;
   parentTemplateId?: string;
 }) {
-  await insertOne(db, templateResourcesTable, {
+  await seedRow(db, templateResourcesTable, {
     tenantId: args.tenantId,
     slug: args.slug,
     kind: args.kind,

package/src/template-resolver/testing.ts

@@ -2,8 +2,8 @@
 // `@cosmicdrift/kumiko-bundled-features/template-resolver/testing`.
 // No bun:test here — callers register cases with their own test runner.
 
-import { insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
 import type { ResolveRequest, TemplateResource } from "./api";
 import { TemplateNotFoundError } from "./api";
 import {
@@ -50,7 +50,7 @@ type SeedTemplateArgs = {
 };
 
 async function seedTemplate(db: DbConnection, args: SeedTemplateArgs): Promise<void> {
-  await insertOne(db, templateResourcesTable, {
+  await seedRow(db, templateResourcesTable, {
     tenantId: args.tenantId,
     slug: args.slug,
     kind: args.kind,
@@ -74,10 +74,11 @@ export async function assertConsumerHandlesNotFound(
   const { tenantId } = opts;
   let rejected = false;
   let err: unknown;
+  const slug = `conformance-not-found-${crypto.randomUUID()}`;
   try {
     await consumer.resolve({
       tenantId,
-      slug: "conformance-not-found-slug",
+      slug,
       kind: "mail-html",
       locale: "de",
     });

package/src/tier-engine/feature.ts

@@ -217,6 +217,7 @@ export function createTierEngineFeature<
     r.writeHandler(
       createSetTenantTierWrite({
         onAssigned: (tenantId, tier) => onTierAssigned.fn(tenantId, tier),
+        validTiers: opts.tierMap ? new Set(Object.keys(opts.tierMap)) : undefined,
       }),
     );
     r.queryHandler(getTenantTierQuery);
@@ -452,19 +453,30 @@ export function createTierEngineFeature<
         // tier-assignment-Row, die der seed-Pfad nicht anlegt) und prüft das
         // Fenster gegen die aktuelle Zeit. Nur auf dem disabled-Gate-Pfad
         // konsultiert. inserted_at ist immutable → pro Tenant einmal lesen.
-        const startedMemo = new Map<TenantId, number>();
+        // Promise-memo (not a plain value cache): N concurrent requests for the
+        // same fresh tenant must await the SAME in-flight fetchOne, not each
+        // fire their own — a plain `Map<TenantId, number>` set AFTER the await
+        // lets every concurrent caller miss the cache and issue a redundant
+        // read (benign but wasteful on a signup burst).
+        const startedMemo = new Map<TenantId, Promise<number | undefined>>();
         const trialGate: TrialGate = async (tenantId, featureName) => {
           if (!trialFeatures.has(featureName)) return false;
-          let startedMs = startedMemo.get(tenantId);
-          if (startedMs === undefined) {
-            const row = await fetchOne<{ insertedAt?: Temporal.Instant }>(deps.db, tenantTable, {
+          let startedMsPromise = startedMemo.get(tenantId);
+          if (startedMsPromise === undefined) {
+            startedMsPromise = fetchOne<{ insertedAt?: Temporal.Instant }>(deps.db, tenantTable, {
               id: tenantId,
-            });
-            // Tenant-Row noch nicht projiziert (Replay-Race) → keinen Miss
-            // memoizen, beim nächsten Request neu lesen.
-            if (row?.insertedAt === undefined) return false;
-            startedMs = row.insertedAt.epochMilliseconds;
-            startedMemo.set(tenantId, startedMs);
+            }).then((row) => row?.insertedAt?.epochMilliseconds);
+            // Evict on rejection too — a transient DB error must not poison
+            // every future call for this tenant with the same cached rejection.
+            startedMsPromise.catch(() => startedMemo.delete(tenantId));
+            startedMemo.set(tenantId, startedMsPromise);
+          }
+          const startedMs = await startedMsPromise;
+          // Tenant-Row noch nicht projiziert (Replay-Race) → keinen Miss
+          // memoizen, beim nächsten Request neu lesen.
+          if (startedMs === undefined) {
+            startedMemo.delete(tenantId);
+            return false;
           }
           return isTrialActive(startedMs, nowMs(), trial.durationHours);
         };

package/src/tier-engine/handlers/set-tenant-tier.write.ts

@@ -44,6 +44,12 @@ export type SetTenantTierOptions = {
    *  Cache aktualisieren kann (der Executor-Write feuert den postSave-Hook
    *  nicht). Ohne tierMap kein Resolver → no-op. */
   readonly onAssigned?: (tenantId: TenantId, tier: string) => void;
+  /** Tier-Namen aus der tierMap-Closure — ohne sie (storage-only-Mode) bleibt
+   *  `tier` unvalidiert außer Length/Non-Empty. Mit ihr rejected der Handler
+   *  einen unbekannten Tier-Namen statt ihn stillschweigend durchzuschreiben
+   *  (featuresForTier gibt für unbekannte Namen defensiv ein leeres Set
+   *  zurück — der Tenant verliert sonst lautlos alle Tier-Gates). */
+  readonly validTiers?: ReadonlySet<string>;
 };
 
 export function createSetTenantTierWrite(opts: SetTenantTierOptions = {}) {
@@ -51,7 +57,11 @@ export function createSetTenantTierWrite(opts: SetTenantTierOptions = {}) {
     name: "set-tenant-tier",
     schema: z.object({
       tenantId: z.string().min(1),
-      tier: z.string().min(1).max(50),
+      tier: z
+        .string()
+        .min(1)
+        .max(50)
+        .refine((t) => !opts.validTiers || opts.validTiers.has(t), { message: "unknown tier" }),
     }),
     access: { roles: ["SystemAdmin"] },
     handler: async (event, ctx) => {

package/src/user/__tests__/stream-tenant-backfill.integration.test.ts

@@ -0,0 +1,186 @@
+// #762 — backfillUserStreamTenants: pre-#497 user streams live on the
+// creating tenant; post-#497 the executor addresses SYSTEM_TENANT_ID, so
+// legacy users version-conflict on every write (password-reset collapses to
+// invalid_token). The backfill retenants + renumbers per aggregate in global
+// id order — including the split-stream case the raw #497-changeset SQL
+// crashes on (legacy tenant v1..n AND post-#497 SYSTEM events for the same
+// aggregate → events_aggregate_version_uq violation).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { append, createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestDb,
+  type TestDb,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { backfillUserStreamTenants } from "../db/queries/stream-tenant-backfill";
+import { userEntity, userTable } from "../schema/user";
+
+const T1 = "00000000-0000-4000-8000-000000000011" as TenantId;
+const LEGACY_USER = "aaaaaaaa-0000-4000-8000-000000000001";
+const SPLIT_USER = "aaaaaaaa-0000-4000-8000-000000000002";
+const MODERN_USER = "aaaaaaaa-0000-4000-8000-000000000003";
+
+let testDb: TestDb;
+
+const executor = createEventStoreExecutor(userTable, userEntity, { entityName: "user" });
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, userEntity, "user");
+  await createEventsTable(testDb.db);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(
+    `TRUNCATE kumiko_events, kumiko_snapshots, kumiko_archived_streams, read_users RESTART IDENTITY CASCADE`,
+  );
+});
+
+async function appendUserEvent(
+  aggregateId: string,
+  tenantId: TenantId,
+  expectedVersion: number,
+  type: string,
+  payload: Record<string, unknown>,
+): Promise<void> {
+  await append(testDb.db, {
+    aggregateId,
+    aggregateType: "user",
+    tenantId,
+    expectedVersion,
+    type,
+    payload,
+    metadata: { userId: "test-migrator" },
+  });
+}
+
+async function streamRows(
+  aggregateId: string,
+): Promise<ReadonlyArray<{ tenant_id: string; version: number; type: string }>> {
+  return (await asRawClient(testDb.db).unsafe(
+    `SELECT "tenant_id", "version", "type" FROM "kumiko_events"
+      WHERE "aggregate_id" = $1::uuid ORDER BY "id" ASC`,
+    [aggregateId],
+  )) as ReadonlyArray<{ tenant_id: string; version: number; type: string }>;
+}
+
+function seedUserRow(id: string, tenantId: TenantId, version: number) {
+  return asRawClient(testDb.db).unsafe(
+    `INSERT INTO "read_users" ("id", "tenant_id", "email", "display_name", "locale", "password_hash", "status", "version")
+     VALUES ($1::uuid, $2::uuid, $3, 'Legacy', 'de', 'x', 'active', $4)`,
+    [id, tenantId, `${id.slice(0, 8)}@example.com`, version],
+  );
+}
+
+describe("backfillUserStreamTenants (#762)", () => {
+  test("legacy stream: retenanted to SYSTEM, versions contiguous, executor write works again", async () => {
+    await appendUserEvent(LEGACY_USER, T1, 0, "user.created", { email: "l@example.com" });
+    await appendUserEvent(LEGACY_USER, T1, 1, "user.updated", { changes: { displayName: "L" } });
+    await seedUserRow(LEGACY_USER, T1, 2);
+
+    const result = await backfillUserStreamTenants(testDb.db);
+    expect(result.aggregatesMigrated).toBe(1);
+    expect(result.eventsMigrated).toBe(2);
+    expect(result.failed).toHaveLength(0);
+
+    const rows = await streamRows(LEGACY_USER);
+    expect(rows.map((r) => r.tenant_id)).toEqual([SYSTEM_TENANT_ID, SYSTEM_TENANT_ID]);
+    expect(rows.map((r) => r.version)).toEqual([1, 2]);
+
+    // The actual #762 symptom: an optimistic-locked executor update with the
+    // row version now targets a stream that HAS that version — no conflict.
+    const tdb = createTenantDb(testDb.db, SYSTEM_TENANT_ID, "system");
+    const writeRes = await executor.update(
+      { id: LEGACY_USER, version: 2, changes: { displayName: "After" } },
+      createSystemUser(SYSTEM_TENANT_ID),
+      tdb,
+    );
+    expect(writeRes.isSuccess).toBe(true);
+  });
+
+  test("split stream (legacy + post-#497 SYSTEM events) merges in global id order", async () => {
+    // Legacy: created + updated on T1 (v1, v2). Then a post-#497 lifecycle
+    // write appended v1 on SYSTEM — the split the raw changeset-SQL trips on.
+    await appendUserEvent(SPLIT_USER, T1, 0, "user.created", { email: "s@example.com" });
+    await appendUserEvent(SPLIT_USER, T1, 1, "user.updated", { changes: { a: 1 } });
+    await appendUserEvent(SPLIT_USER, SYSTEM_TENANT_ID, 0, "user.updated", {
+      changes: { status: "restricted" },
+    });
+    await seedUserRow(SPLIT_USER, T1, 2);
+
+    const result = await backfillUserStreamTenants(testDb.db);
+    expect(result.aggregatesMigrated).toBe(1);
+    expect(result.eventsMigrated).toBe(3);
+    expect(result.failed).toHaveLength(0);
+
+    const rows = await streamRows(SPLIT_USER);
+    expect(rows.map((r) => r.tenant_id)).toEqual([
+      SYSTEM_TENANT_ID,
+      SYSTEM_TENANT_ID,
+      SYSTEM_TENANT_ID,
+    ]);
+    // Renumbered by global event id: created, updated(T1), updated(SYSTEM).
+    expect(rows.map((r) => r.version)).toEqual([1, 2, 3]);
+    expect(rows[0]?.type).toBe("user.created");
+  });
+
+  test("idempotent: second run finds nothing; modern SYSTEM streams untouched", async () => {
+    await appendUserEvent(MODERN_USER, SYSTEM_TENANT_ID, 0, "user.created", {
+      email: "m@example.com",
+    });
+    await appendUserEvent(LEGACY_USER, T1, 0, "user.created", { email: "l@example.com" });
+
+    const first = await backfillUserStreamTenants(testDb.db);
+    expect(first.aggregatesMigrated).toBe(1);
+
+    const second = await backfillUserStreamTenants(testDb.db);
+    expect(second.aggregatesMigrated).toBe(0);
+    expect(second.eventsMigrated).toBe(0);
+
+    const modern = await streamRows(MODERN_USER);
+    expect(modern).toHaveLength(1);
+    expect(modern[0]?.version).toBe(1);
+  });
+
+  test("stale snapshots dropped, archived-stream marker moves to SYSTEM", async () => {
+    await appendUserEvent(LEGACY_USER, T1, 0, "user.created", { email: "l@example.com" });
+    await asRawClient(testDb.db).unsafe(
+      `INSERT INTO "kumiko_snapshots" ("aggregate_id", "aggregate_type", "tenant_id", "version", "state")
+       VALUES ($1::uuid, 'user', $2::uuid, 1, '{}'::jsonb)`,
+      [LEGACY_USER, T1],
+    );
+    await asRawClient(testDb.db).unsafe(
+      `INSERT INTO "kumiko_archived_streams" ("tenant_id", "aggregate_id", "aggregate_type", "archived_by")
+       VALUES ($1::uuid, $2::uuid, 'user', 'test')`,
+      [T1, LEGACY_USER],
+    );
+
+    const result = await backfillUserStreamTenants(testDb.db);
+    expect(result.failed).toHaveLength(0);
+
+    const snapshots = (await asRawClient(testDb.db).unsafe(
+      `SELECT count(*)::int AS n FROM "kumiko_snapshots" WHERE "aggregate_id" = $1::uuid`,
+      [LEGACY_USER],
+    )) as ReadonlyArray<{ n: number }>;
+    expect(snapshots[0]?.n).toBe(0);
+
+    const archived = (await asRawClient(testDb.db).unsafe(
+      `SELECT "tenant_id" FROM "kumiko_archived_streams" WHERE "aggregate_id" = $1::uuid`,
+      [LEGACY_USER],
+    )) as ReadonlyArray<{ tenant_id: string }>;
+    expect(archived).toHaveLength(1);
+    expect(archived[0]?.tenant_id).toBe(SYSTEM_TENANT_ID);
+  });
+});