@cosmicdrift/kumiko-samples 0.388.0 → 0.390.0

package/packages/bundled-features/src/template-resolver/web/use-document-tiptap-model.ts

@@ -0,0 +1,138 @@
+import { useEditor, useEditorState } from "@tiptap/react";
+import { useMemo, useState } from "react";
+import { createDocumentEditorExtensions } from "./document-editor-extensions.ts";
+import { activeStateOf, type PanelKind, previewsKey } from "./document-tiptap-helpers.ts";
+import type { DocumentEditorProps, DocumentResourcePreview } from "./document-toolbar-blocks.ts";
+import { useEditorHandleReport } from "./editor-handle.ts";
+import { useStableByKey } from "./use-stable-by-key.ts";
+
+type Translate = (key: string, params?: Readonly<Record<string, unknown>>) => string;
+
+export function documentEditorLabels(t: Translate) {
+  return {
+    placeholderLabel: t("template-resolver.documentEditor.placeholder"),
+    imageLabel: t("template-resolver.documentEditor.image"),
+    imageBlockLabel: t("template-resolver.documentEditor.imageBlock"),
+    pageBreakLabel: t("template-resolver.documentEditor.pageBreak"),
+    buttonLabel: t("template-resolver.documentEditor.button"),
+    stepsLabel: t("template-resolver.documentEditor.steps"),
+    imagesLabel: t("template-resolver.documentEditor.images"),
+  };
+}
+
+export type DocumentEditorLabels = ReturnType<typeof documentEditorLabels>;
+
+function useDocumentExtensions(input: {
+  readonly labels: DocumentEditorLabels;
+  readonly canvas: boolean;
+  readonly variableLabels: Readonly<Record<string, string>>;
+  readonly systemVariables: readonly string[];
+  readonly resourcePreviews: Readonly<Record<string, DocumentResourcePreview>>;
+}) {
+  const { canvas, variableLabels, systemVariables, resourcePreviews } = input;
+  const {
+    placeholderLabel,
+    imageLabel,
+    imageBlockLabel,
+    pageBreakLabel,
+    buttonLabel,
+    stepsLabel,
+    imagesLabel,
+  } = input.labels;
+  const stableLabels = useStableByKey(variableLabels, JSON.stringify(variableLabels));
+  const stableSystem = useStableByKey(systemVariables, systemVariables.join("\n"));
+  const stablePreviews = useStableByKey(resourcePreviews, previewsKey(resourcePreviews));
+  const extensions = useMemo(
+    () =>
+      createDocumentEditorExtensions({
+        placeholder: placeholderLabel,
+        image: imageLabel,
+        pageBreak: pageBreakLabel,
+        button: buttonLabel,
+        steps: stepsLabel,
+        images: imagesLabel,
+        imageBlock: imageBlockLabel,
+        variableLabels: stableLabels,
+        systemVariables: stableSystem,
+        resourcePreviews: stablePreviews,
+        blockLabels: canvas,
+      }),
+    [
+      placeholderLabel,
+      imageLabel,
+      imageBlockLabel,
+      pageBreakLabel,
+      buttonLabel,
+      stepsLabel,
+      imagesLabel,
+      stableLabels,
+      stableSystem,
+      stablePreviews,
+      canvas,
+    ],
+  );
+  return { extensions, stableLabels };
+}
+
+export type DocumentTiptapModelInput = Pick<
+  DocumentEditorProps,
+  "id" | "value" | "onChange" | "readOnly" | "onEditorReady"
+> & {
+  readonly variableLabels: Readonly<Record<string, string>>;
+  readonly systemVariables: readonly string[];
+  readonly resourcePreviews: Readonly<Record<string, DocumentResourcePreview>>;
+  readonly canvas: boolean;
+};
+
+export function useDocumentTiptapModel(input: DocumentTiptapModelInput, t: Translate) {
+  const { id, value, onChange, readOnly } = input;
+  const [openPanel, setOpenPanel] = useState<PanelKind | null>(null);
+  const [canvasScroller, setCanvasScroller] = useState<HTMLElement | null>(null);
+  const [showHtml, setShowHtml] = useState(false);
+  const labels = documentEditorLabels(t);
+  const { extensions, stableLabels } = useDocumentExtensions({
+    labels,
+    canvas: input.canvas,
+    variableLabels: input.variableLabels,
+    systemVariables: input.systemVariables,
+    resourcePreviews: input.resourcePreviews,
+  });
+
+  // The node views are built from labels and previews, so a changed set
+  // rebuilds the editor; its content is re-read from `value`.
+  const editor = useEditor(
+    {
+      extensions,
+      content: value,
+      editable: !readOnly,
+      // Suspense (DocumentContentEditor's lazy boundary) speculatively mounts
+      // this component before committing it; immediate render would create an
+      // editor instance during that throwaway pass.
+      immediatelyRender: false,
+      editorProps: { attributes: { id } },
+      onUpdate: ({ editor: e }) => onChange(e.getHTML()),
+    },
+    [extensions],
+  );
+  useEditorHandleReport(editor, input.onEditorReady);
+
+  // @tiptap/react v3 does not re-render on selection-only transactions, so
+  // active states must come from a subscription.
+  const activeState = useEditorState({
+    editor,
+    selector: ({ editor: e }) => (e === null ? null : activeStateOf(e, showHtml)),
+  });
+
+  return {
+    openPanel,
+    setOpenPanel,
+    canvasScroller,
+    setCanvasScroller,
+    showHtml,
+    setShowHtml,
+    labels,
+    stableLabels,
+    editor,
+    activeState,
+  };
+}

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

@@ -1,4 +1,23 @@
 [
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "Event-store write helpers for user, membership and tenant tests",
+    "detail": "The user/testing and tenant/testing subpaths export updateUserViaEventStore, softDeleteUserViaEventStore, setMembershipRolesViaEventStore, deleteMembershipViaEventStore and updateTenantViaEventStore. updateTenantViaEventStore addresses the stream of the seed SystemAdmin's tenant by default, where tenants created in tests live. Tests use them to change event-sourced rows through the event store instead of the projection tables. Both subpaths now import @cosmicdrift/kumiko-testing and therefore load under Bun only, like tenant-lifecycle/testing; import user/seeding or tenant/seeding where Node has to load the seed helpers."
+  },
+  {
+    "version": "0.390.0",
+    "type": "breaking",
+    "title": "Tenant streams and rows live on the system tenant, seed defaults changed",
+    "detail": "Tenants created, renamed or toggled by a SystemAdmin whose session tenant was neither 0001 nor the SYSTEM tenant landed in the event stream, read row and search bucket of that session tenant, so later updates could not find them. The tenant entity is now declared systemStream with tenancy global, so every writer (create, update, enable and disable, request and cancel destruction, the destroy job stages) addresses the stream on SYSTEM_TENANT_ID. seedTenant, seedUser, seedAdmin and seedAdminGuarded default to createSystemUser(SYSTEM_TENANT_ID) and write the tenant to SYSTEM whatever tenant an explicit by acts from; managed-pages and compliance-profiles seeds default to createSystemUser(tenantId). Existing memberships written by an admin of another tenant sit on that admin's stream while read_tenant_memberships.tenant_id carries the member tenant; after the backfill streamTenantId equals tenantId for them. New export backfillTenantStreamTenants from the tenant feature, the boot step runStreamTenantBackfillOnBoot in server-runtime, EsOperationType gains \"stream-migration\", built on the generic backfillAggregateStreamTenants in shared (backfillUserStreamTenants keeps its signature).",
+    "migration": "Nothing to run: runProdApp (api, all-in-one) and runWorkerApp search for legacy tenant, membership and user streams on every boot, before the boot seeds respectively before the worker starts, and fix what they find. A boot with nothing left reads only events of other tenants than SYSTEM (plus the membership events) and does no rebuild or reindex. It merges split tenant streams onto SYSTEM_TENANT_ID, moves each membership stream to the tenantId of its payload, moves legacy user streams, removes stale search documents from the old buckets, and where streams moved rebuilds tenant:projection:tenant-entity, tenant:projection:tenant-membership-entity and user:projection:user-entity and reindexes the tenant and user search indexes. Legacy streams written by old pods during a rolling deploy are fixed on the next boot. A row in kumiko_es_operations (stream-tenant-backfill:<user|tenant>:derived-pending) marks a run in progress so that a crash after the moves still gets its rebuild and reindex. Parallel boots are serialized by a Postgres advisory lock; failures are logged (aggregateId, step, error) and retried on the next boot. A process without a search adapter leaves the work to one that has it. Library users can call backfillTenantStreamTenants or backfillUserStreamTenantsWithDerivedState directly. Code that read tenant streams with loadAggregate(db, tenantId, \"tenant\") or appended tenant events with the tenant id as stream tenant must use SYSTEM_TENANT_ID. Consumer workarounds that wrote tenant streams under a SystemAdmin `by` (for example an executor update with TestUsers.systemAdmin) are no longer needed, because the stream is always SYSTEM. Seeds that relied on the old by default (TestUsers.systemAdmin) now get the system user as audit actor. Apps without a search backend set `search: \"none\"` on runProdApp and runWorkerApp, otherwise the stream-tenant backfill stays deferred in every process that has no search adapter."
+  },
+  {
+    "version": "0.390.0",
+    "type": "improvement",
+    "title": "Tests no longer write event-sourced tables directly",
+    "detail": "Integration tests for users, memberships, tenants and user-data-rights change event-sourced rows through the event store or the real commands and reset them with resetTestTables. seedDestroyingTenant in tenant-lifecycle/testing now writes the status through the event store and throws when the tenant stream does not live on the seed SystemAdmin's tenant. Nothing changes for apps; the packages are only republished."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

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

@@ -71,6 +71,7 @@ export function collectAssignableAppRoles(
 
 export function createTenantFeature(options?: TenantFeatureOptions): FeatureDefinition {
   return defineFeature("tenant", (r) => {
+    r.adoptsBundledLists();
     r.describe(
       "Registers the three core multi-tenancy entities \u2014 `tenant`, `tenant-membership`, and `tenant-invitation` (DB tables `read_tenants`, `read_tenant_memberships`, and `read_tenant_invitations`) \u2014 along with write handlers for create/update/disable/enable/addMember/removeMember/updateMemberRoles and the matching queries. It also declares a set of per-tenant config keys (companyName, timezone, locale, SMTP credentials) and system-only keys (priceModel, maxUsers) via `r.config({ keys: { ... } })`. Use this feature in every multi-tenant app; membership resolution and invitation flows depend on it, and `auth-email-password` requires it.",
     );

package/packages/bundled-features/src/tenant/handlers/cancel-invitation.write.ts

@@ -59,7 +59,7 @@ export const cancelInvitationWrite = defineWriteHandler({
       db,
       { id: event.payload.invitationId, version: invitation["version"] as number }, // @cast-boundary db-row
       event.user,
-      ctx.redis,
+      ctx.services.redis,
     );
     if (cancelFailure) return cancelFailure;
 

package/packages/bundled-features/src/tenant/handlers/memberships.query.ts

@@ -10,7 +10,7 @@ import { tenantTable } from "../schema/tenant.ts";
 export const membershipsQuery = defineQueryHandler({
   name: "memberships",
   schema: z.object({ userId: z.string() }),
-  // Called via ctx.queryAs(systemUser, ...) during login/switch-tenant, or
+  // Called via ctx.dispatch.queryAs(systemUser, ...) during login/switch-tenant, or
   // directly by tenant admins managing memberships in the admin UI.
   access: { roles: [SYSTEM_ROLE, "SystemAdmin"] },
   description:

package/packages/bundled-features/src/tenant/handlers/remove-member.write.ts

@@ -129,7 +129,7 @@ export const removeMemberWrite = defineWriteHandler({
     // member is logged out but the membership is intact — safe direction.
     const revoker = ctx.registry.getWriteHandler(REVOKE_ALL_SESSIONS_QN);
     if (revoker) {
-      await ctx.writeAs(createSystemUser(event.payload.tenantId), REVOKE_ALL_SESSIONS_QN, {
+      await ctx.dispatch.writeAs(createSystemUser(event.payload.tenantId), REVOKE_ALL_SESSIONS_QN, {
         userId: event.payload.userId,
         tenantId: event.payload.tenantId,
       });
@@ -148,7 +148,7 @@ export const removeMemberWrite = defineWriteHandler({
       tenantId: event.payload.tenantId,
       actor: event.user,
       streamTenantId,
-      redis: ctx.redis,
+      redis: ctx.services.redis,
     });
     if (cancelFailure !== undefined) return cancelFailure;
 

package/packages/bundled-features/src/tenant/handlers/team-list.query.ts

@@ -1,4 +1,4 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { isUndefinedTable, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   definePagedQueryHandler,
@@ -7,7 +7,7 @@ import {
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { errorCodeOf, isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { userSessionTable } from "../../sessions/index.ts";
 import { decryptStoredPii, mapWithConcurrency } from "../../shared/index.ts";
@@ -142,7 +142,7 @@ export const teamListQuery = definePagedQueryHandler({
         // ponytail: lean sample apps (admin-console) mount auth without
         // sessions — store_user_sessions never gets pushed. Integration tests
         // may seed the table without mounting the feature; prod mounts both.
-        if (errorCodeOf(err) !== "42P01") throw err;
+        if (!isUndefinedTable(err)) throw err;
       }
     }
 

package/packages/bundled-features/src/tenant/handlers/update-member-roles.write.ts

@@ -181,7 +181,7 @@ export const updateMemberRolesWrite = defineWriteHandler({
     // requires, see above).
     const revoker = ctx.registry.getWriteHandler(REVOKE_ALL_SESSIONS_QN);
     if (revoker) {
-      await ctx.writeAs(
+      await ctx.dispatch.writeAs(
         createSystemUser(targetTenantId),
         REVOKE_ALL_SESSIONS_QN,
         revokeSessionsPayload(event.payload.userId, targetTenantId, event.user),

package/packages/bundled-features/src/tenant/index.ts

@@ -17,6 +17,11 @@ export {
   tenantEntity,
   tenantTable,
 } from "./schema/tenant.ts";
+export {
+  backfillTenantStreamTenants,
+  type TenantStreamBackfillDeps,
+  type TenantStreamBackfillResult,
+} from "./stream-tenant-backfill.ts";
 export {
   OWNER_INVITE_ROLE_OPTIONS,
   TENANT_FEATURE,

package/packages/bundled-features/src/tenant/invited-membership.ts

@@ -87,7 +87,12 @@ export async function grantInvitedMembershipRole(db: DbRunner, options: InvitedM
   const updateResult = await membershipExecutor.update(
     { id: existing.id, version: existing.version, changes: { roles: JSON.stringify(roles) } },
     createSystemUser(options.tenantId),
-    createTenantDb({ db, tenantId: options.tenantId, mode: "system" }),
+    createTenantDb({
+      db,
+      tenantId: options.tenantId,
+      mode: "system",
+      reason: "invite acceptance adds the membership in the invited tenant, not the caller's",
+    }),
   );
   if (!updateResult.isSuccess) return updateResult;
   return grantedMembership(true, roles);

package/packages/bundled-features/src/tenant/schema/tenant.ts

@@ -21,6 +21,9 @@ export const tenantEntity = createEntity({
   description:
     "A tenant, the isolated workspace every other record belongs to, holding its key and display name, whether it is enabled, and its destruction-lifecycle state.",
   table: "read_tenants",
+  // Tenant-independent aggregate: stream, row and search bucket live on SYSTEM_TENANT_ID, not on the acting user's tenant.
+  systemStream: true,
+  tenancy: "global",
   // `tenant.id` is the `tenantId` value referenced by every other table as a foreign key.
   // Every `tenantId` column is UUID, so `tenant.id` must also be UUID; otherwise
   // the tenant lookup never finds a match. The default is `gen_random_uuid()`.
@@ -32,7 +35,7 @@ export const tenantEntity = createEntity({
       personal: false,
       reason: "technical_reference",
     }),
-    // Subject is the tenant record itself: tenant events live in the writer's (system) tenant stream, so `personal: "tenant"` would not resolve to this tenant.
+    // Subject is the tenant record itself: the stream lives on SYSTEM_TENANT_ID, so `personal: "tenant"` would not resolve to this tenant.
     name: createTextField({
       required: true,
       maxLength: 200,

package/packages/bundled-features/src/tenant/seeding.ts

@@ -35,12 +35,14 @@ import {
   fetchOne,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
-  type AppContext,
+  attachOutsideTransaction,
   createSystemUser,
+  type HandlerContext,
   HookPhases,
   type Registry,
   type SaveContext,
   type SessionUser,
+  SYSTEM_TENANT_ID,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { getUnscopedAggregateStreamMaxVersion } from "@cosmicdrift/kumiko-framework/event-store";
@@ -48,7 +50,6 @@ import {
   createDeferringNotify,
   createLifecycleHooks,
 } from "@cosmicdrift/kumiko-framework/pipeline";
-import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 import { assertAssignableMembershipRoles } from "./membership-roles.ts";
 import { tenantMembershipEntity, tenantMembershipsTable } from "./membership-table.ts";
 import { tenantEntity, tenantTable } from "./schema/tenant.ts";
@@ -99,28 +100,29 @@ export type SeedTenantOptions = {
 // care about hooks need no changes).
 export type SeedTenantHooks = {
   readonly registry: Registry;
-  readonly context: AppContext;
+  readonly context: HandlerContext;
 };
 
 function buildSeedHookNotify(
-  context: AppContext,
+  context: HandlerContext,
   scopedUser: SessionUser,
   targetTenantId: TenantId,
   notifyTiming: "deferUntilCommit" | "inline",
-): AppContext["notify"] {
-  const notifyFactory = context._notifyFactory;
+): HandlerContext["notify"] {
+  const { services, lifecycle } = context;
+  const notifyFactory = services._notifyFactory;
   if (!notifyFactory) return context.notify;
-  const notifyAfterCommit = (context._notifyAfterCommitFactory ?? notifyFactory)(
+  const notifyAfterCommit = (services._notifyAfterCommitFactory ?? notifyFactory)(
     scopedUser,
     targetTenantId,
   );
   if (notifyTiming === "inline") return notifyAfterCommit;
   // Still inside the caller's write tx: delivery DB work must not wait for an app-pool slot.
-  const notifyInsideTransaction = (context._notifyInTransactionFactory ?? notifyFactory)(
+  const notifyInsideTransaction = (services._notifyInTransactionFactory ?? notifyFactory)(
     scopedUser,
     targetTenantId,
   );
-  const scheduleAfterCommit = context.scheduleAfterCommit;
+  const scheduleAfterCommit = lifecycle.afterCommit;
   if (!scheduleAfterCommit) return notifyInsideTransaction;
   return createDeferringNotify({
     registry: context.registry,
@@ -131,6 +133,26 @@ function buildSeedHookNotify(
   });
 }
 
+type TrialGate = (tenantId: TenantId, featureName: string) => Promise<boolean>;
+
+function isTrialGate(candidate: unknown): candidate is TrialGate {
+  return typeof candidate === "function";
+}
+
+function scopedHasFeature(
+  context: HandlerContext,
+  targetTenantId: TenantId,
+): HandlerContext["hasFeature"] {
+  const features = context.services.effectiveFeatures;
+  // Keep the caller's hasFeature when no effectiveFeatures is wired (always-on apps).
+  if (!features) return context.hasFeature;
+  const trialGate: unknown = Reflect.get(features, "trialGate");
+  return async (featureName) => {
+    if (features(targetTenantId).has(featureName)) return true;
+    return isTrialGate(trialGate) ? trialGate(targetTenantId, featureName) : false;
+  };
+}
+
 // Shared by seedTenant/seedTenantMembership/auth-email-password's
 // seedUserWithPassword: fires the same entity-scoped postSave hooks the
 // real dispatcher would (registry.getEntityPostSaveHooks by entityName),
@@ -140,70 +162,43 @@ function buildSeedHookNotify(
 // wired at server-boot and out of reach here).
 //
 // Tenant re-scope: when `targetTenantId` is set we rebuild the
-// tenant-bound pieces of the context (`_tenantId`, `db`, `notify`,
-// `hasFeature`, `user.tenantId`) — a shallow `{ ...ctx, _tenantId }` left
-// closures over the caller's tenant (self-signup is anonymous/system).
-// `query`/`write` bridges still share the caller's identity; hooks that
-// need a full identity switch use `writeAs`/`queryAs`.
+// tenant-bound pieces of the context (`db`, `notify`, `hasFeature`,
+// `user.tenantId`) — a shallow copy left closures over the caller's tenant
+// (self-signup is anonymous/system). `query`/`write` bridges still share the
+// caller's identity; hooks that need a full identity switch use `writeAs`/`queryAs`.
 //
-// afterCommit: when `hooks.context.scheduleAfterCommit` is present
+// afterCommit: when `hooks.context.lifecycle.afterCommit` is present
 // (HandlerContext from a live write), afterCommit hooks are queued onto the
 // dispatcher's sink and flush post-commit. Without a sink (fixture / plain
 // Connection) they still fire immediately — there is no outer TX to wait for.
 // `runner` comes from the caller, which already holds a declared DbRunner —
 // a TenantDb exposes no runner back out to feature code.
 function scopeSeedHookContext(
-  context: AppContext,
+  context: HandlerContext,
   targetTenantId: TenantId,
   runner: DbRunner,
   // The afterCommit sink is snapshotted when it flushes, so a hook scheduled from inside an
   // afterCommit-phase hook would be dropped: that phase must notify inline.
   notifyTiming: "deferUntilCommit" | "inline",
-): AppContext {
+): HandlerContext {
   const db = createTenantDb({
     db: runner,
     tenantId: targetTenantId,
     mode: "system",
-    tracer: context.tracer,
-    meter: context.meter,
-    signal: context.signal,
+    reason: "seed hooks run in the seeded tenant, regardless of the caller's tenant",
+    tracer: context.obs.tracer,
+    meter: context.obs.meter,
+    signal: context.lifecycle.signal,
   });
-
-  // HandlerContext carries `user`; AppContext only `systemUser`. Prefer the
-  // live handler user when present so notify/hasFeature keep a real SessionUser.
-  const handlerUser = (context as { user?: SessionUser }).user;
-  const baseUser: SessionUser | undefined = handlerUser ?? context.systemUser;
-  const scopedUser: SessionUser | undefined = baseUser
-    ? { ...baseUser, tenantId: targetTenantId }
-    : undefined;
-
-  const notify = scopedUser
-    ? buildSeedHookNotify(context, scopedUser, targetTenantId, notifyTiming)
-    : context.notify;
-
-  const features = context.effectiveFeatures as
-    | (((tenantId: TenantId) => ReadonlySet<string>) & {
-        trialGate?: (tenantId: TenantId, featureName: string) => Promise<boolean>;
-      })
-    | undefined;
-  const hasFeature = features
-    ? async (featureName: string): Promise<boolean> => {
-        if (features(targetTenantId).has(featureName)) return true;
-        if (!features.trialGate) return false;
-        return features.trialGate(targetTenantId, featureName);
-      }
-    : "hasFeature" in context
-      ? // Keep caller's hasFeature when no effectiveFeatures (always-on apps).
-        (context as { hasFeature?: (n: string) => Promise<boolean> }).hasFeature
-      : undefined;
+  const scopedUser: SessionUser = { ...context.user, tenantId: targetTenantId };
+  const notify = buildSeedHookNotify(context, scopedUser, targetTenantId, notifyTiming);
 
   return {
     ...context,
-    _tenantId: targetTenantId,
-    db,
+    db: attachOutsideTransaction(db, undefined),
     ...(notify !== undefined ? { notify } : {}),
-    ...(scopedUser && "user" in context ? { user: scopedUser } : {}),
-    ...(hasFeature ? { hasFeature } : {}),
+    user: scopedUser,
+    hasFeature: scopedHasFeature(context, targetTenantId),
   };
 }
 
@@ -212,7 +207,7 @@ export async function fireEntityPostSave(
   pseudoType: string,
   entityData: SaveContext,
   // Undefined for tenant-agnostic entities (user has no tenant_id column at
-  // seed time) — keeps hooks.context._tenantId as the caller passed it.
+  // seed time) — keeps hooks.context.user as the caller passed it.
   target?: { readonly tenantId: TenantId; readonly db: DbRunner },
 ): Promise<void> {
   // skip: caller opted out of hooks (existing fixture/test call-sites that
@@ -233,8 +228,8 @@ export async function fireEntityPostSave(
         : scopeSeedHookContext(hooks.context, target.tenantId, target.db, "inline"),
       HookPhases.afterCommit,
     );
-  if (scopedContext.scheduleAfterCommit) {
-    scopedContext.scheduleAfterCommit(runAfterCommit);
+  if (scopedContext.lifecycle.afterCommit) {
+    scopedContext.lifecycle.afterCommit(runAfterCommit);
   } else {
     await runAfterCommit();
   }
@@ -255,12 +250,15 @@ export async function seedTenant(
   options: SeedTenantOptions,
   hooks?: SeedTenantHooks,
 ): Promise<{ id: TenantId }> {
-  const by = options.by ?? TestUsers.systemAdmin;
-  // executor.create expects a TenantDb with an .insert()-API, not the raw
-  // DbConnection. Although the tenant aggregate is not tenant-scoped, the
-  // wrapper is required by the runtime API. by.tenantId is sufficient; unlike
-  // seedTenantMembership, no override semantics are needed.
-  const tdb = createTenantDb({ db, tenantId: by.tenantId, mode: "system" });
+  const by = options.by ?? createSystemUser(SYSTEM_TENANT_ID);
+  // The tenant aggregate is global: its row and stream live on SYSTEM_TENANT_ID whatever tenant `by` acts from.
+  const tdb = createTenantDb({
+    db,
+    tenantId: SYSTEM_TENANT_ID,
+    mode: "system",
+    reason:
+      "the global tenant aggregate lives on SYSTEM_TENANT_ID whatever tenant the seeding actor acts from",
+  });
 
   const existing = await fetchOne(db, tenantTable, { id: options.id });
   if (existing) return { id: options.id };
@@ -324,7 +322,12 @@ export async function seedTenantMembership(
   const by = options.by ?? createSystemUser(options.tenantId);
   // System-scoped TenantDb: payload.tenantId may differ from an explicit
   // `by` override; stream tenant still follows `by` via streamTenantFor.
-  const tdb = createTenantDb({ db, tenantId: options.tenantId, mode: "system" });
+  const tdb = createTenantDb({
+    db,
+    tenantId: options.tenantId,
+    mode: "system",
+    reason: "membership seed targets an explicit tenant that may differ from the actor's",
+  });
 
   // Idempotency: duplicate seeds are common across beforeEach-resets where
   // only certain tables get truncated. A plain executor.create would trip

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

@@ -0,0 +1,115 @@
+// One-time migration for tenant and tenant-membership streams written before
+// `tenant` became a systemStream/global entity. Those streams, read rows and
+// search docs sit on whichever tenant the acting admin's session carried.
+//
+// Runs at boot (server-runtime) and can be called by hand. Idempotent: a second
+// run finds nothing left to move.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
+import {
+  backfillAggregateStreamTenants,
+  createSearchBucketCleanup,
+  type DerivedStateMode,
+  rebuildAndReindex,
+  type StreamBackfillResult,
+  type StreamBackfillStepFailure,
+  stepFailures,
+} from "../shared/index.ts";
+
+const TENANT_AGGREGATE = "tenant";
+const MEMBERSHIP_AGGREGATE = "tenant-membership";
+const TENANT_PROJECTION = "tenant:projection:tenant-entity";
+const MEMBERSHIP_PROJECTION = "tenant:projection:tenant-membership-entity";
+
+export type TenantStreamBackfillResult = {
+  readonly tenants: StreamBackfillResult;
+  readonly memberships: StreamBackfillResult;
+  // Tenants for which at least one stale search doc bucket was cleaned.
+  readonly searchDocsRemoved: number;
+  readonly projectionsRebuilt: readonly string[];
+  readonly reindexedTenants: number;
+  // Per-step failures across the whole run; step names the failing stage.
+  readonly failures: readonly StreamBackfillStepFailure[];
+};
+
+export type TenantStreamBackfillDeps = {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+  readonly searchAdapter?: SearchAdapter;
+  readonly derived?: DerivedStateMode;
+  readonly scanTenantIds?: readonly string[];
+  readonly onFirstCandidate?: () => Promise<"proceed" | "skip">;
+};
+
+export async function backfillTenantStreamTenants(
+  deps: TenantStreamBackfillDeps,
+): Promise<TenantStreamBackfillResult> {
+  const {
+    db,
+    registry,
+    searchAdapter,
+    derived = "if-moved",
+    scanTenantIds,
+    onFirstCandidate,
+  } = deps;
+  const scan = {
+    ...(scanTenantIds && { scanTenantIds }),
+    ...(onFirstCandidate && { onFirstCandidate }),
+  };
+  const searchCleanup = createSearchBucketCleanup(searchAdapter, TENANT_AGGREGATE);
+
+  const tenants = await backfillAggregateStreamTenants(db, {
+    aggregateType: TENANT_AGGREGATE,
+    target: { kind: "system" },
+    beforeMove: searchCleanup.beforeMove,
+    ...scan,
+  });
+  const memberships = await backfillAggregateStreamTenants(db, {
+    aggregateType: MEMBERSHIP_AGGREGATE,
+    target: { kind: "payload-tenant" },
+    ...scan,
+  });
+  const failures: StreamBackfillStepFailure[] = [
+    ...stepFailures("tenant-streams", tenants.failed),
+    ...stepFailures("membership-streams", memberships.failed),
+  ];
+
+  const moved = tenants.aggregatesMigrated + memberships.aggregatesMigrated > 0;
+  if (!moved && derived === "if-moved") {
+    return emptyDerived({ tenants, memberships, searchCleanup, failures });
+  }
+
+  const rebuilt = await rebuildAndReindex({
+    db,
+    registry,
+    ...(searchAdapter && { searchAdapter }),
+    projections: [TENANT_PROJECTION, MEMBERSHIP_PROJECTION],
+    searchEntity: TENANT_AGGREGATE,
+  });
+  return {
+    tenants,
+    memberships,
+    searchDocsRemoved: searchCleanup.cleanedAggregates(),
+    projectionsRebuilt: rebuilt.projectionsRebuilt,
+    reindexedTenants: rebuilt.reindexedRows,
+    failures: [...failures, ...rebuilt.failures],
+  };
+}
+
+function emptyDerived(args: {
+  readonly tenants: StreamBackfillResult;
+  readonly memberships: StreamBackfillResult;
+  readonly searchCleanup: { readonly cleanedAggregates: () => number };
+  readonly failures: readonly StreamBackfillStepFailure[];
+}): TenantStreamBackfillResult {
+  return {
+    tenants: args.tenants,
+    memberships: args.memberships,
+    searchDocsRemoved: args.searchCleanup.cleanedAggregates(),
+    projectionsRebuilt: [],
+    reindexedTenants: 0,
+    failures: args.failures,
+  };
+}