@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/tier-engine/handlers/get-tenant-tier.query.ts

@@ -0,0 +1,32 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { buildEntityTable, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { defineQueryHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { type TierAssignmentRow, tierAssignmentEntity } from "../entity.js";
+
+// Liest das Tier-Assignment eines BELIEBIGEN Tenants (cross-tenant) für den
+// tier-admin-Screen. SystemAdmin-only. get-active-tier liest nur den eigenen
+// Tenant — hier ein "system"-mode TenantDb auf den Ziel-Tenant (kein Filter),
+// damit der Admin das Tier fremder Tenants sehen kann. null wenn noch keins.
+
+const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEntity);
+
+const GET_TENANT_TIER_REASON = "SystemAdmin reads the tier of the tenant named in the payload";
+
+export const getTenantTierQuery = defineQueryHandler({
+  name: "get-tenant-tier",
+  description:
+    "Returns the tier-assignment of any given tenant including where it came from (manual grant, billing sync or signup default), or null; use it to look up another tenant's plan.",
+  schema: z.object({ tenantId: z.string().min(1) }),
+  access: { roles: ["SystemAdmin"] },
+  escapeHatch: {
+    grants: ["unsafeRaw"],
+    reason: GET_TENANT_TIER_REASON,
+  },
+  handler: async (query, ctx) => {
+    const tenantId = query.payload.tenantId as TenantId; // @cast-boundary engine-bridge
+    const tdb = createTenantDb(ctx.db.unsafeRaw(GET_TENANT_TIER_REASON), tenantId, "system");
+    const row = await fetchOne<TierAssignmentRow>(tdb, tierAssignmentTable, { tenantId });
+    return row ?? null;
+  },
+});

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

@@ -0,0 +1,108 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  buildEntityTable,
+  createEventStoreExecutor,
+  createTenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import { defineWriteHandler, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { tierAssignmentAggregateId } from "../aggregate-id.js";
+import { type TierAssignmentRow, tierAssignmentEntity } from "../entity.js";
+
+// SystemAdmin setzt das Tier eines BELIEBIGEN Tenants — manueller Grant ohne
+// Billing. Cross-tenant, daher SystemAdmin-only (kein TenantAdmin: sonst
+// Gratis-Self-Upgrade).
+//
+// **Cross-tenant-Mechanik:** ein "system"-mode TenantDb auf den Ziel-Tenant legt
+// KEINEN Tenant-Filter an (tenant-db.ts:141 — mode==="system" überspringt ihn);
+// der executor-user wird ebenfalls auf den Ziel-Tenant gestellt, sonst landet das
+// Event im Stream des Admins (Memory feedback_event_store_tenant_consistency).
+// Das set.write-"override-user"-Muster trägt NICHT für beliebige Tenants — es
+// funktioniert nur für SYSTEM_TENANT_ID (immer im IN-Filter). Dies ist das
+// auto-default-Hook-Muster (feature.ts), generalisiert auf einen Request-Handler.
+//
+// `source: "manual"` markiert den Grant, damit ein späterer Stripe→Tier-Sync ihn
+// nicht plättet. Upsert: ein Aggregat pro Tenant (deterministische aggregate-id).
+//
+// **Effective-Set-Invalidation (kritisch):** der Executor-Write feuert NICHT
+// den `tier-assignment:postSave`-entityHook (Hooks laufen nur im Entity-
+// Handler-Pfad, nicht bei direktem executor.create/update). Ohne Cache-Update
+// bliebe das Feature-Gate auf dem alten Tier hängen — die Projektion zeigt
+// "pro", das Gate verhält sich weiter wie "free", bis der Prozess neu startet.
+// Daher ruft der Handler nach erfolgreichem Write `opts.onAssigned(tenantId,
+// tier)`; feature.ts verdrahtet das auf denselben Cache-Update wie der Hook
+// (storage-only ohne tierMap = no-op).
+
+const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEntity);
+const executor = createEventStoreExecutor(tierAssignmentTable, tierAssignmentEntity, {
+  entityName: "tier-assignment",
+});
+
+const SET_TENANT_TIER_REASON = "SystemAdmin assigns the tier of the tenant named in the payload";
+
+export type SetTenantTierOptions = {
+  /** Nach erfolgreichem Write aufgerufen, damit feature.ts den Resolver-
+   *  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 = {}) {
+  return defineWriteHandler({
+    name: "set-tenant-tier",
+    description:
+      "Assigns a tier to any tenant as a manual grant without a billing purchase, marking it so a later billing sync will not overwrite it, and applies the new feature set immediately.",
+    schema: z.object({
+      tenantId: z.string().min(1),
+      tier: z
+        .string()
+        .min(1)
+        .max(50)
+        .refine((t) => !opts.validTiers || opts.validTiers.has(t), { message: "unknown tier" }),
+    }),
+    access: { roles: ["SystemAdmin"] },
+    escapeHatch: {
+      grants: ["unsafeRaw"],
+      reason: SET_TENANT_TIER_REASON,
+    },
+    handler: async (event, ctx) => {
+      const tenantId = event.payload.tenantId as TenantId; // @cast-boundary engine-bridge
+      const rawDb = ctx.db.unsafeRaw(SET_TENANT_TIER_REASON);
+      const tdb = createTenantDb(rawDb, tenantId, "system");
+      const systemUser = { ...event.user, tenantId };
+      const tier = event.payload.tier;
+
+      const existing = await fetchOne<TierAssignmentRow>(tdb, tierAssignmentTable, { tenantId });
+
+      if (existing) {
+        const result = await executor.update(
+          {
+            id: existing.id,
+            version: existing.version,
+            changes: { tier, source: "manual" },
+          },
+          systemUser,
+          tdb,
+        );
+        if (!result.isSuccess) return result;
+        opts.onAssigned?.(tenantId, tier);
+        return { isSuccess: true as const, data: { tenantId, tier, isNew: false } };
+      }
+
+      const result = await executor.create(
+        { id: tierAssignmentAggregateId(tenantId), tier, source: "manual", tenantId },
+        systemUser,
+        tdb,
+      );
+      if (!result.isSuccess) return result;
+      opts.onAssigned?.(tenantId, tier);
+      return { isSuccess: true as const, data: { tenantId, tier, isNew: true } };
+    },
+  });
+}

package/packages/bundled-features/src/tier-engine/i18n.ts

@@ -0,0 +1,31 @@
+// @runtime client
+// Server + client i18n for the tier-admin actionForm. Single source of
+// truth: r.translations({ keys: TIER_ENGINE_I18N }) registers these
+// server-side, defaultTranslations derives the client-side locale bundle
+// from the same map so the two can't drift.
+
+import {
+  type TranslationsByLocale,
+  translationsByLocaleFromKeys,
+} from "@cosmicdrift/kumiko-renderer";
+
+type LocalizedString = { readonly en: string };
+
+export const TIER_ENGINE_I18N: Readonly<Record<string, LocalizedString>> = {
+  "screen:tier-admin.title": { en: "Assign tier manually" },
+  "tier-admin.screen.subtitle": {
+    en: "Assign a tier to a tenant as a manual grant, without a purchase.",
+  },
+  "tier-admin.explainer": {
+    en: "Grant a tenant a tier without a purchase. The grant is marked as “manual” and a later billing sync won't overwrite it.",
+  },
+  "tier-admin.error.noTiers": {
+    en: "This app has no TierMap configured — there are no assignable tiers.",
+  },
+  "tier-engine:entity:__action-form__:field:tenantId": { en: "Tenant" },
+  "tier-engine:entity:__action-form__:field:tier": { en: "New tier" },
+  "tier-admin.submit": { en: "Assign tier" },
+};
+
+export const defaultTranslations: TranslationsByLocale =
+  translationsByLocaleFromKeys(TIER_ENGINE_I18N);

package/packages/bundled-features/src/tier-engine/index.ts

@@ -0,0 +1,32 @@
+// Public API of the tier-engine bundled-feature.
+//
+// **What downstream apps import:**
+//   - `tierEngineFeature` — register at app boot via runProdApp/setupTestStack
+//   - `composeApp` — call to derive feature-set + caps from tier+addOns
+//   - `TierMap` / `AddOnMap` — types for the app's own tier/add-on definitions
+//   - `tierAssignmentEntity` — for migrations + drizzle-schema-generation
+//   - `TierEngineHandlers` / `TierEngineQueries` — qualified handler names
+
+export { tierAssignmentAggregateId } from "./aggregate-id.js";
+export {
+  type AddOnDefinition,
+  type AddOnMap,
+  type ComposeAppInput,
+  type ComposedApp,
+  composeApp,
+  type TierDefinition,
+  type TierMap,
+} from "./compose-app.js";
+export { TIER_ENGINE_FEATURE, TierEngineHandlers, TierEngineQueries } from "./constants.js";
+export { tierAssignmentEntity } from "./entity.js";
+export {
+  type CreateTierEngineOptions,
+  createTierEngineFeature,
+  tierEngineFeature,
+} from "./feature.js";
+export {
+  createTierResolver,
+  type TierResolver,
+  type TierResolverDeps,
+} from "./tier-resolver.js";
+export { isTrialActive, type TrialPolicy } from "./trial.js";

package/packages/bundled-features/src/tier-engine/tier-resolver.ts

@@ -0,0 +1,38 @@
+// Generic tier-resolver factory. Extracted from the near-identical
+// tier-resolver.ts app copies in show-pony and publicstatus (infra#446) — the
+// only per-app variables were the TierName union and its caps/defaults, so
+// both are now factory parameters.
+
+import { buildEntityTable, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { CapLimitContext } from "../cap-counter/index.js";
+import { tierAssignmentEntity } from "./entity.js";
+
+export type TierResolverDeps<TTier extends string, TCaps> = {
+  readonly capsForTier: (tier: TTier, context: CapLimitContext) => TCaps | Promise<TCaps>;
+  readonly isTierName: (value: string) => value is TTier;
+  readonly defaultTier: TTier;
+};
+
+export function createTierResolver<TTier extends string, TCaps>(
+  deps: TierResolverDeps<TTier, TCaps>,
+) {
+  const tierAssignmentTable = buildEntityTable("tier-assignment", tierAssignmentEntity);
+
+  async function resolveTier(db: TenantDb): Promise<TTier> {
+    const row = await db.fetchOne<{ tier?: unknown }>(tierAssignmentTable, {
+      tenantId: db.tenantId,
+    });
+    const tier = row?.tier;
+    return typeof tier === "string" && deps.isTierName(tier) ? tier : deps.defaultTier;
+  }
+
+  async function resolveTierCaps(db: TenantDb, context: CapLimitContext = {}): Promise<TCaps> {
+    return deps.capsForTier(await resolveTier(db), context);
+  }
+
+  return { tierAssignmentTable, resolveTier, resolveTierCaps };
+}
+
+export type TierResolver<TTier extends string, TCaps> = ReturnType<
+  typeof createTierResolver<TTier, TCaps>
+>;

package/packages/bundled-features/src/tier-engine/trial.ts

@@ -0,0 +1,26 @@
+// Trial-Phase: ein neuer Tenant bekommt für eine Karenzzeit ab seinem
+// Anlage-Datum (inserted_at der tier-assignment-Row — rebuild-stabil aus dem
+// Create-Event) zusätzlich die Features eines höheren Tiers, unabhängig vom
+// gespeicherten Tier. Rein zeit-abgeleitet: kein Stored-Flag, kein Scheduler,
+// automatischer Ablauf. Die App definiert die Policy (welcher Tier, wie lange);
+// die tier-engine wendet sie im Resolver an.
+
+export interface TrialPolicy {
+  // Tier, dessen Features während der Trial-Phase zusätzlich freigeschaltet
+  // werden (muss ein Key der tierMap sein, sonst greift kein Feature).
+  readonly tier: string;
+  // Länge der Trial-Phase ab inserted_at, in Stunden (720 = 30 Tage). Stunden
+  // statt Tage: Temporal.Instant kennt keine Kalender-Tage, 720h ist die
+  // ehrliche, DST-unabhängige Dauer.
+  readonly durationHours: number;
+}
+
+// Reine Millis-Arithmetik auf epochMilliseconds (die beide Seiten — Projektions-
+// Row und Now — liefern). Kein Date, keine TZ.
+export function isTrialActive(
+  startedAtEpochMs: number,
+  nowEpochMs: number,
+  durationHours: number,
+): boolean {
+  return nowEpochMs < startedAtEpochMs + durationHours * 3_600_000;
+}

package/packages/bundled-features/src/tier-engine/web/client-plugin.tsx

@@ -0,0 +1,21 @@
+// @runtime client
+// Client-feature factory for tier-engine. Supplies the default translations
+// for the declarative tier-admin actionForm (registered server-side via
+// r.screen in the feature); the app places the screen only via r.nav.
+
+import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { TIER_ENGINE_FEATURE } from "../constants.js";
+import { defaultTranslations } from "../i18n.js";
+
+export type TierEngineClientOptions = {
+  /** Per-key overrides over the default bundles (de/en). */
+  readonly translations?: TranslationsByLocale;
+};
+
+export function tierEngineClient(options?: TierEngineClientOptions): ClientFeatureDefinition {
+  return {
+    name: TIER_ENGINE_FEATURE,
+    translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
+  };
+}

package/packages/bundled-features/src/tier-engine/web/index.ts

@@ -0,0 +1,7 @@
+// @runtime client
+// Public exports für die Browser-Seite des tier-engine Features. Konsumiert
+// über `@cosmicdrift/kumiko-bundled-features/tier-engine/web` — die
+// Server-Seite (createTierEngineFeature) lebt unter
+// `@cosmicdrift/kumiko-bundled-features/tier-engine` und hat keine React-Deps.
+
+export { type TierEngineClientOptions, tierEngineClient } from "./client-plugin.js";

package/packages/bundled-features/src/user/changes.json

@@ -0,0 +1,48 @@
+[
+  {
+    "version": "0.271.0",
+    "type": "improvement",
+    "title": "systemScope handlers get a default per-tenant+handler rate limit; user:me opts out (fw#2861).",
+    "detail": "`user` mounts under `r.systemScope()`, so its write/query handlers without their own `rateLimit` now default to `{ per: \"tenant+handler\", limit: 600, windowSeconds: 60 }` once an app has a `RateLimitResolver` configured (framework change, see kumiko-framework changes.json 0.271.0). `user:query:user:me` (`user:me.query.ts`) declares `rateLimit: { disabled: true, reason: \"...\" }` — it is a self-scoped read of the caller's own identity record, hit on every page load, and a per-tenant bucket would throttle the whole tenant's page loads instead of just that one handler's traffic."
+  },
+  {
+    "version": "0.218.1",
+    "type": "improvement",
+    "title": "user.email searchable \u2014 reindex required after upgrade",
+    "detail": "email gained searchable for roster lookup. buildSearchDocument only runs on write; existing rows need reindexEntity(\"user\") (or the reindex job) plus Meili configure for the new attribute.",
+    "migration": "After deploying, run reindexEntity(\"user\") (or the existing reindex job) so pre-upgrade user rows appear in roster search."
+  },
+  {
+    "version": "0.218.0",
+    "type": "fix",
+    "title": "user-list: system-scope search; membership roles on tenants; emailVerified sort",
+    "detail": "systemScope entityList search uses SYSTEM_TENANT_ID (was session tenant \u2192 Meili miss/500). Tenants column shows membership roles (Offlot Demo (TenantAdmin)). emailVerified sortable; email also searchable for roster lookup. Global roles stay SystemAdmin-only \u2014 TenantAdmin/Admin live on membership (Team \u2192 Members)."
+  },
+  {
+    "version": "0.217.0",
+    "type": "improvement",
+    "title": "user-list: roles multiSelect + tenants column; roles editable as SystemAdmin (fw#2384 follow-up)",
+    "detail": "user.roles is now createMultiSelectField (jsonb string[], options=[SystemAdmin]) so entityEdit shows a real multi-select instead of a raw JSON text box \u2014 SystemAdmins can promote another SystemAdmin from the UI. user-list columns gain roles + tenants; tenants is a derived field filled by the list handler from memberships (platform roster was unusable without tenant context). switch-tenant + auth-client parseRoles accept jsonb arrays (string-only deserialize dropped SystemAdmin on tenant switch). Soft-deleted users stay hidden by default.",
+    "migration": "Run `kumiko-schema generate` and apply \u2014 migrates read_users.roles from text to jsonb USING roles::jsonb. Existing JSON array strings (`[]`, `[\"SystemAdmin\"]`) convert cleanly. Consumers that wrote roles as a JSON-encoded string via user:create/update should pass string[] instead (parseRoles still accepts both on read)."
+  },
+  {
+    "version": "0.167.1",
+    "type": "breaking",
+    "title": "user.locale no longer defaults to \"de\" (fw#1637).",
+    "detail": "The entity-level default contradicted tenant-settings' own \"en\" default and silently overrode any app or tenant locale configuration for every new user. locale now stays unset until the client or a resolution chain provides one. Consumers that already fall back with `user.locale ?? \"en\"` are unaffected in shape but now see null instead of \"de\".",
+    "migration": "Run `kumiko-schema generate` and apply \u2014 the migration emits `ALTER TABLE read_users ALTER COLUMN locale DROP DEFAULT`. Note that DROP DEFAULT only affects future inserts: existing rows keep the \"de\" the old default wrote, which no user ever chose. Your app therefore splits into pre-bump users on \"de\" and post-bump users on null, and each group resolves to a different language. Decide deliberately: either keep the old values (and state that pre-bump users stay German), or run `UPDATE read_users SET locale = NULL WHERE locale = 'de'` once so every user follows the same chain \u2014 the latter only if no UI ever let users edit the field, otherwise it erases real choices. If your app relied on the implicit German default, set an explicit fallback instead (fw#1653)."
+  },
+  {
+    "version": "0.167.1",
+    "type": "improvement",
+    "title": "user.timezone field, wired into ctx.tz (fw#1636).",
+    "detail": "The user entity gains a `timezone` field (createTzField, no default). buildHandlerContext passes it to ctx.tz.user; the fallback chain stays tenant.timezone, then \"UTC\". Before this, ctx.tz.tenant and ctx.tz.user both hardcoded \"UTC\" while the plumbing already accepted per-request values.",
+    "migration": "Run `kumiko-schema generate` and apply \u2014 the migration adds `read_users.timezone`. No backfill: an unset timezone falls through to the tenant's, exactly as before the field existed."
+  },
+  {
+    "version": "0.165.3",
+    "type": "improvement",
+    "title": "user.displayName is searchable via derived Meili (fw#1610).",
+    "detail": "displayName is userOwned PII and now searchable through the decrypt-into-Meili path; forget purges the index entry with the subject key."
+  }
+]

package/packages/bundled-features/src/user/command-schemas.ts

@@ -0,0 +1,15 @@
+// Command-input schemas for the user write handlers, re-exposed for external
+// consumers — primarily migration mappers that need to write events directly
+// into the core `user` stream via `eventStore.appendRaw` (Marten-bypass) and
+// must validate their payloads against the exact handler contract.
+//
+// See `tenant/command-schemas.ts` for the same pattern + the schema-vs-event-
+// payload caveat (strip-id, defaults, sensitive, compound-type flattening).
+
+import { createWrite } from "./handlers/create.write.js";
+import { updateWrite } from "./handlers/update.write.js";
+
+export const UserCommandSchemas = {
+  create: createWrite.schema,
+  update: updateWrite.schema,
+} as const;

package/packages/bundled-features/src/user/constants.ts

@@ -0,0 +1,32 @@
+// @runtime client
+// Feature name
+export const USER_FEATURE = "user" as const;
+
+/** Assignable global (cross-tenant) roles on user.roles — SystemAdmin is the
+ *  platform operator. Membership roles (TenantAdmin/Admin/User/…) live on
+ *  tenant-membership, not here. */
+export const GLOBAL_ROLE_OPTIONS = ["SystemAdmin"] as const;
+
+// Qualified write handler names. Handlers carry the "user:" entity prefix so
+// field-level access rules (passwordHash system-only etc.) are wired up.
+export const UserHandlers = {
+  create: "user:write:user:create",
+  update: "user:write:user:update",
+} as const;
+
+// Qualified query handler names
+export const UserQueries = {
+  me: "user:query:user:me",
+  detail: "user:query:user:detail",
+  list: "user:query:user:list",
+  findForAuth: "user:query:user:find-for-auth",
+} as const;
+
+// Error codes
+export const UserErrors = {
+  emailAlreadyExists: "email_already_exists",
+  cannotEditOtherUser: "cannot_edit_other_user",
+  cannotModifyGlobalRoles: "cannot_modify_global_roles",
+  cannotDemoteLastSystemAdmin: "cannot_demote_last_system_admin",
+  roleElevationForbidden: "role_elevation_forbidden",
+} as const;

package/packages/bundled-features/src/user/db/queries/stream-tenant-backfill.ts

@@ -0,0 +1,113 @@
+// #762 — one-time migration tooling for pre-#497 user event streams.
+//
+// #497 made `user` a systemStream entity: every executor op addresses the
+// stream on SYSTEM_TENANT_ID. Streams created before that live on whichever
+// tenant created them ("scattered"), so post-#497 writes version-conflict
+// against the empty SYSTEM stream. The raw UPDATE documented in the #497
+// changeset breaks as soon as an aggregate has BOTH a legacy stream and
+// post-#497 SYSTEM events (split stream — e.g. a skipOptimisticLock
+// lifecycle write appended v1 on SYSTEM while v1..n live on the old
+// tenant): retenanting then trips events_aggregate_version_uq.
+//
+// This tool merges per aggregate: all user events, ordered by global event
+// id, are renumbered 1..n and retenanted to SYSTEM_TENANT_ID — two-phase
+// version writes (negative interim values) dodge the unique index while the
+// per-aggregate transaction is in flight. Snapshots of migrated aggregates
+// are dropped (version numbering changed; the next snapshotting load
+// recreates them); archived-stream markers move with the stream.
+//
+// Idempotent: the candidate query only matches aggregates that still have
+// non-SYSTEM events. One failing aggregate does not abort the run — the
+// rest of the estate migrates, failures are reported.
+//
+// After a run, rebuild the user projection so read_users.tenant_id reflects
+// the stream move: rebuildProjection("user:projection:user-entity", ...) or
+// the jobs:job:projection-rebuild job.
+
+import { asRawClient, transaction, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+
+export type UserStreamBackfillResult = {
+  readonly aggregatesMigrated: number;
+  readonly eventsMigrated: number;
+  readonly failed: ReadonlyArray<{ readonly aggregateId: string; readonly error: string }>;
+};
+
+export async function backfillUserStreamTenants(
+  db: DbConnection,
+): Promise<UserStreamBackfillResult> {
+  const candidates = (await unsafeReadRetrying(
+    db,
+    `SELECT DISTINCT "aggregate_id" FROM "kumiko_events"
+      WHERE "aggregate_type" = 'user' AND "tenant_id" <> $1::uuid`,
+    [SYSTEM_TENANT_ID],
+  )) as ReadonlyArray<{ aggregate_id: string }>;
+
+  let aggregatesMigrated = 0;
+  let eventsMigrated = 0;
+  const failed: Array<{ aggregateId: string; error: string }> = [];
+
+  for (const { aggregate_id } of candidates) {
+    try {
+      eventsMigrated += await migrateAggregate(db, aggregate_id);
+      aggregatesMigrated++;
+    } catch (e) {
+      failed.push({
+        aggregateId: aggregate_id,
+        error: e instanceof Error ? e.message : String(e),
+      });
+    }
+  }
+  return { aggregatesMigrated, eventsMigrated, failed };
+}
+
+async function migrateAggregate(db: DbConnection, aggregateId: string): Promise<number> {
+  return transaction(db, async (tx) => {
+    const raw = asRawClient(tx);
+    // Global id order = commit-adjacent replay order; merges a split stream
+    // (legacy tenant + SYSTEM) into one consistent version sequence.
+    const events = (await raw.unsafe(
+      `SELECT "id" FROM "kumiko_events"
+        WHERE "aggregate_type" = 'user' AND "aggregate_id" = $1::uuid
+        ORDER BY "id" ASC
+        FOR UPDATE`,
+      [aggregateId],
+    )) as ReadonlyArray<{ id: bigint | string }>;
+
+    // Phase 1: negative interim versions — real versions are always >= 1, so
+    // nothing can collide with events_aggregate_version_uq mid-migration.
+    for (const [i, ev] of events.entries()) {
+      await raw.unsafe(
+        `UPDATE "kumiko_events" SET "tenant_id" = $1::uuid, "version" = $2 WHERE "id" = $3`,
+        [SYSTEM_TENANT_ID, -(i + 1), ev.id],
+      );
+    }
+    // Phase 2: final contiguous 1..n.
+    for (const [i, ev] of events.entries()) {
+      await raw.unsafe(`UPDATE "kumiko_events" SET "version" = $1 WHERE "id" = $2`, [i + 1, ev.id]);
+    }
+
+    // Version numbering changed → any snapshot of this aggregate is stale.
+    await raw.unsafe(`DELETE FROM "kumiko_snapshots" WHERE "aggregate_id" = $1::uuid`, [
+      aggregateId,
+    ]);
+
+    // Archived markers key on (tenant_id, aggregate_id) — move them with the
+    // stream, keeping an existing SYSTEM marker if both exist.
+    await raw.unsafe(
+      `INSERT INTO "kumiko_archived_streams" ("tenant_id", "aggregate_id", "aggregate_type", "archived_at", "archived_by", "reason")
+        SELECT $1::uuid, "aggregate_id", "aggregate_type", "archived_at", "archived_by", "reason"
+          FROM "kumiko_archived_streams"
+         WHERE "aggregate_id" = $2::uuid AND "tenant_id" <> $1::uuid
+        ON CONFLICT DO NOTHING`,
+      [SYSTEM_TENANT_ID, aggregateId],
+    );
+    await raw.unsafe(
+      `DELETE FROM "kumiko_archived_streams" WHERE "aggregate_id" = $1::uuid AND "tenant_id" <> $2::uuid`,
+      [aggregateId, SYSTEM_TENANT_ID],
+    );
+
+    return events.length;
+  });
+}

package/packages/bundled-features/src/user/feature.ts

@@ -0,0 +1,61 @@
+import {
+  defineFeature,
+  EXT_PRINCIPAL_STATUS,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createWrite } from "./handlers/create.write.js";
+import { detailQuery } from "./handlers/detail.query.js";
+import { findForAuthQuery } from "./handlers/find-for-auth.query.js";
+import { listQuery } from "./handlers/list.query.js";
+import { meQuery } from "./handlers/me.query.js";
+import { updateWrite } from "./handlers/update.write.js";
+import { USER_I18N } from "./i18n.js";
+import { principalStatusPlugin } from "./principal-status.js";
+import { userEntity } from "./schema/user.js";
+import { userEditScreen, userListScreen } from "./screens.js";
+
+// The user feature holds the cross-tenant user identity. `systemScope()` means
+// queries and writes bypass the tenant filter — a user exists above any tenant.
+// Membership + tenant-specific roles live in the tenant feature.
+export function createUserFeature(): FeatureDefinition {
+  return defineFeature("user", (r) => {
+    r.describe(
+      "Manages the cross-tenant user identity: the `read_users` table holds each user's email, `displayName`, global `roles`, `emailVerified` flag, and lifecycle `status` (active / restricted / deletionRequested / deleted). Because users exist above any individual tenant, the feature runs with `r.systemScope()` \u2014 membership and tenant-specific roles live in the `tenant` feature instead. Add this feature whenever your app needs a persistent, tenant-agnostic user record that auth and GDPR pipelines can reference.",
+    );
+    r.uiHints({
+      displayLabel: "User Identity",
+      category: "identity",
+      recommended: true,
+    });
+    r.systemScope();
+    r.entity("user", userEntity);
+
+    // Self-extension: `user` declares AND fulfils principalStatus (precedent:
+    // tier-engine/feature.ts) — wires the blocked-principal check into every stack that mounts `user`.
+    r.extendsRegistrar(EXT_PRINCIPAL_STATUS, {});
+    r.useExtension(EXT_PRINCIPAL_STATUS, "user", principalStatusPlugin);
+
+    const handlers = {
+      create: r.writeHandler(createWrite),
+      update: r.writeHandler(updateWrite),
+    };
+
+    const queries = {
+      me: r.queryHandler(meQuery),
+      detail: r.queryHandler(detailQuery),
+      list: r.queryHandler(listQuery),
+      findForAuth: r.queryHandler(findForAuthQuery),
+    };
+
+    // Cross-tenant SystemAdmin platform screens. Inert until an app navs them;
+    // list/detail/create/update handlers above already sit on the QNs that
+    // entityList/entityEdit resolve by convention (user:query:user:{list,detail},
+    // user:write:user:{create,update}).
+    r.screen(userListScreen);
+    r.screen(userEditScreen);
+
+    r.translations({ keys: USER_I18N });
+
+    return { handlers, queries };
+  });
+}