@cosmicdrift/kumiko-samples 0.352.0 → 0.354.0

package/packages/bundled-features/src/shared/encrypt-for-direct-write.ts

@@ -3,8 +3,10 @@ import {
   collectPiiSubjectFields,
   configuredPiiSubjectKms,
   encryptPiiFieldValues,
+  KeyErasedError,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { subjectErasedConflict } from "@cosmicdrift/kumiko-framework/errors";
 
 // Unmanaged direct-write stores (r.unmanagedTable) skip the executor, so its
 // PII encryption never runs — every insert of subject-annotated fields must
@@ -18,12 +20,17 @@ export async function encryptForDirectWrite(
 ): Promise<Record<string, unknown>> {
   const kms = configuredPiiSubjectKms();
   if (!kms) return row;
-  return encryptPiiFieldValues(
-    row,
-    entity,
-    collectPiiSubjectFields(entity),
-    kms,
-    { requestId: requestContext.get()?.requestId ?? fallbackRequestId },
-    { entityName },
-  );
+  try {
+    return await encryptPiiFieldValues(
+      row,
+      entity,
+      collectPiiSubjectFields(entity),
+      kms,
+      { requestId: requestContext.get()?.requestId ?? fallbackRequestId },
+      { entityName },
+    );
+  } catch (e) {
+    if (e instanceof KeyErasedError) throw subjectErasedConflict(e);
+    throw e;
+  }
 }

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

@@ -1,4 +1,5 @@
 export { collectErasureFailure, throwIfErasureFailed } from "./assert-erased.js";
+export { assertNoWhereRuleInOwnershipWrite } from "./assert-no-where-rule-in-ownership-write.js";
 export {
   type ChunkedMigrationOptions,
   type ChunkedMigrationResult,
@@ -14,17 +15,18 @@ export { decryptStoredPii } from "./decrypt-stored-pii.js";
 export { encryptForDirectWrite } from "./encrypt-for-direct-write.js";
 export { entitiesOf } from "./entities-of.js";
 export { isWithinGracePeriod } from "./grace-period.js";
-export { hasWhereRule } from "./has-where-rule.js";
 export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash.js";
 export { isTenantDb } from "./is-tenant-db.js";
 export { createLockoutCounter, type LockoutCounterState } from "./lockout-counter.js";
 export { mapWithConcurrency } from "./map-with-concurrency.js";
 export {
   denyUnlessJoinRowParentVisible,
+  hostRowIsGone,
   joinRowParentIsVisible,
   parentRowIsVisible,
 } from "./parent-visibility.js";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing.js";
+export { rateLimitedTextResponse } from "./rate-limited-text-response.js";
 export {
   redactBotTokens,
   redactEmailAddresses,
@@ -37,7 +39,7 @@ export {
   signRowBoundGrant,
 } from "./row-bound-grant.js";
 export { runInSubTransaction } from "./run-in-sub-transaction.js";
-export { sessionLocaleField } from "./session-locale-field.js";
+export { registrationLocaleFromRequest, sessionLocaleField } from "./session-locale-field.js";
 export { sessionTimezoneField } from "./session-timezone-field.js";
 export {
   peekTokenSubject,

package/packages/bundled-features/src/shared/parent-visibility.ts

@@ -1,4 +1,8 @@
-import type { EventStoreExecutor, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  buildEntityTable,
+  type EventStoreExecutor,
+  type TenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntityExecutor,
   type EntityDefinition,
@@ -61,6 +65,32 @@ export async function parentRowIsVisible(
   return (await executor.detail({ id: entityId }, user, db)) !== null;
 }
 
+const hostTablesByEntity = new WeakMap<EntityDefinition, ReturnType<typeof buildEntityTable>>();
+
+// True when the host row can never be read again by anyone: its entityType no
+// longer names a registered entity, or the row is hard-deleted / soft-deleted.
+// Deliberately skips the caller's `access.read` ownership (unlike
+// parentRowIsVisible): a row hidden from this caller but alive for another team
+// is NOT gone, and its join row must stay.
+export async function hostRowIsGone(
+  registry: Registry,
+  entityType: string,
+  entityId: string,
+  db: TenantDb,
+): Promise<boolean> {
+  const entity = registry.getEntity(entityType);
+  if (!entity) return true;
+  if (!idShapeMatchesEntity(entity, entityId)) return true;
+
+  let table = hostTablesByEntity.get(entity);
+  if (!table) {
+    table = buildEntityTable(entityType, entity, { relations: registry.getRelations(entityType) });
+    hostTablesByEntity.set(entity, table);
+  }
+  const row = await db.fetchOne(table, { id: entityId });
+  return row === undefined || row["isDeleted"] === true;
+}
+
 // Write-path half of the parentRef gate (fw#2766). Resolves the join entity's
 // own `parentRef` declaration from the registry — the same object the read
 // path's SQL gate reads — so the field names and the allowedTypes allowlist

package/packages/bundled-features/src/shared/rate-limited-text-response.ts

@@ -0,0 +1,11 @@
+import type { RateLimitError } from "@cosmicdrift/kumiko-framework/errors";
+
+export function rateLimitedTextResponse(error: RateLimitError): Response {
+  return new Response("rate limited", {
+    status: 429,
+    headers: {
+      "content-type": "text/plain; charset=utf-8",
+      "retry-after": String(error.details.retryAfterSeconds),
+    },
+  });
+}

package/packages/bundled-features/src/shared/row-bound-grant.ts

@@ -54,6 +54,19 @@ function anchoredPurpose(purpose: string, anchor: string): string {
   return `${purpose}:${anchor}`;
 }
 
+// The HMAC input is `${purpose}:${anchor}:${subject}.${expiresAtMs}` with no
+// length prefixes. Colon-free anchor and subject make the split unambiguous
+// from the right, so two different (purpose, anchor, subject) triples can
+// never share a signature. The purpose may keep colons (tenant-handover
+// namespaces its purpose by entity type).
+function hasDelimiter(value: string): boolean {
+  return value.includes(":");
+}
+
+function isUnambiguousPart(value: string | null | undefined): value is string {
+  return !!value && !hasDelimiter(value);
+}
+
 export function signRowBoundGrant(args: {
   readonly subject: string;
   readonly purpose: string;
@@ -62,6 +75,9 @@ export function signRowBoundGrant(args: {
   readonly secret: string;
   readonly now?: Temporal.Instant;
 }): { readonly token: string; readonly expiresAt: Temporal.Instant } {
+  if (hasDelimiter(args.anchor) || hasDelimiter(args.subject)) {
+    throw new Error("row-bound grant: subject and anchor must not contain ':'");
+  }
   return signToken(
     args.subject,
     anchoredPurpose(args.purpose, args.anchor),
@@ -90,7 +106,7 @@ export async function redeemRowBoundGrant(args: {
   if (!args.secret) return FAILED;
 
   const subject = peekTokenSubject(args.token);
-  if (!subject) return FAILED;
+  if (!isUnambiguousPart(subject)) return FAILED;
 
   // The subject is unverified attacker input at this point, so a lookup that
   // throws on it (e.g. a non-uuid value against a uuid column) must not
@@ -107,7 +123,7 @@ export async function redeemRowBoundGrant(args: {
     });
     return FAILED;
   }
-  if (!anchor) return FAILED;
+  if (!isUnambiguousPart(anchor)) return FAILED;
 
   const verified = verifyToken(
     args.token,

package/packages/bundled-features/src/shared/session-locale-field.ts

@@ -1,3 +1,4 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
 import { canonicalizeLocaleTag, isValidLocaleTag } from "@cosmicdrift/kumiko-framework/i18n";
 
@@ -7,3 +8,9 @@ export function sessionLocaleField(
   if (locale === null || locale === undefined || !isValidLocaleTag(locale)) return {};
   return { locale: canonicalizeLocaleTag(locale) };
 }
+
+// Only an explicit request signal (X-Locale) counts: the boot default is not a
+// choice the new user made.
+export function registrationLocaleFromRequest(): ReturnType<typeof sessionLocaleField> {
+  return sessionLocaleField(requestContext.get()?.locale);
+}

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

@@ -27,7 +27,7 @@ import {
   type EntityDefinition,
   type FeatureRegistrar,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { hasWhereRule } from "../shared/index.js";
+import { assertNoWhereRuleInOwnershipWrite } from "../shared/index.js";
 import { DEFAULT_TAG_ACCESS, TAGS_FEATURE_NAME } from "./constants.js";
 import { createTagAssignmentEntity, tagEntity } from "./entity.js";
 import { createTagAssignmentExecutor } from "./executor.js";
@@ -201,17 +201,7 @@ export function createTagsFeature(opts: TagsFeatureOptions = {}): typeof tagsFea
         "admissible as a host instead.",
     );
   }
-  if (hasWhereRule(opts.ownership?.write)) {
-    throw new Error(
-      "createTagsFeature({ ownership }): ownership.write must not contain a " +
-        '`{ kind: "where" }` rule — where-rules are evaluated only at the SQL ' +
-        "layer (the read path, via buildOwnershipClause). Write paths that " +
-        "consult access.write (userCanCreateFieldRow/userCanWriteFieldRow) can't " +
-        "evaluate them, so such a rule can only ever deny — boot validation " +
-        "rejects it too (fw#2626). Use a `from()` rule for ownership.write, or " +
-        "leave it unset.",
-    );
-  }
+  assertNoWhereRuleInOwnershipWrite("createTagsFeature", opts.ownership?.write);
   const access = resolveAccess(opts);
   return defineFeature(TAGS_FEATURE_NAME, (r) =>
     registerTags(r, access, opts.toggleable, opts.ownership, opts.parents),

package/packages/bundled-features/src/template-resolver/api.ts

@@ -3,7 +3,7 @@
 // ctx.templateResolver at runtime.
 
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
@@ -76,7 +76,7 @@ export type TemplateResolverApi = {
   readonly resolveTemplate: (args: ResolveRequest) => Promise<TemplateResource>;
 };
 
-export function createTemplateResolverApi(db: DbConnection): TemplateResolverApi {
+export function createTemplateResolverApi(db: DbRunner): TemplateResolverApi {
   return {
     findExact: async ({ tenantId, slug, kind, locale, scope }) => {
       const effectiveTenantId = scope === "system" ? SYSTEM_TENANT_ID : tenantId;
@@ -106,7 +106,7 @@ export function createTemplateResolverApi(db: DbConnection): TemplateResolverApi
 }
 
 async function fetchTemplate(
-  db: DbConnection,
+  db: DbRunner,
   tenantId: string,
   slug: string,
   kind: TemplateKind,

package/packages/bundled-features/src/template-resolver/changes.json

@@ -1,4 +1,9 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "template-resolver list filters by every template kind including text-block and ai-prompt"
+  },
   {
     "version": "0.335.0",
     "type": "breaking",

package/packages/bundled-features/src/template-resolver/handlers/list.query.ts

@@ -1,7 +1,7 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-import { RENDER_KINDS, TEMPLATE_STATUSES } from "../constants.js";
+import { TEMPLATE_KINDS, TEMPLATE_STATUSES } from "../constants.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
 
 // List für Admin-UI: filterbar nach kind / locale / status. Liefert
@@ -10,7 +10,7 @@ import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
 export const listQuery = defineQueryHandler({
   name: "list",
   schema: z.object({
-    kind: z.enum(RENDER_KINDS).optional(),
+    kind: z.enum(TEMPLATE_KINDS).optional(),
     locale: z.string().min(2).max(8).optional(),
     status: z.enum(TEMPLATE_STATUSES).optional(),
     includeSystem: z.boolean().default(true),

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

@@ -1,4 +1,23 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "breaking",
+    "title": "createTenantFeature fails the boot when a declared assignable app role is missing from its assignableAppRoles option",
+    "detail": "Final review batch E1: bundled features\n`createTenantFeature` now fails the boot when an `assignableRole` declaration is missing from its `assignableAppRoles` option, because the members and invite screens would otherwise omit the role and a save of the member-roles form would silently strip it. `composeFeatures(includeBundled)` already passes the option. Agent-callable handlers that change access or books now resolve risk `high`: `tenant:write:disable`, `tenant:write:updateMemberRoles`, `user:write:user:update`, `tier-engine:write:set-tenant-tier`, `ledger:write:create-transaction` and `ledger:write:reverse-transaction`. `in_app_messages` gets a `(tenant_id, user_id, created_at)` index. `GET /files/:id/download-url` no longer puts a personal `fileName` into the signed URL; the hint carries a neutral name derived from the MIME type, while `GET /files/:id` still sends the real name in its response header. The forget-subject denial audit event goes through the shared `appendDomainEventCore`, which the pipeline barrel now exports.",
+    "migration": "Pass assignableAppRoles: collectAssignableAppRoles(appFeatures) to createTenantFeature when you mount it by hand; composeFeatures(includeBundled) already does."
+  },
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "tenant:write:disable and tenant:write:updateMemberRoles resolve agent risk high"
+  },
+  {
+    "version": "0.353.0",
+    "type": "breaking",
+    "title": "Tenant names are encrypted under the tenant record and crypto-shredded when the tenant is destroyed",
+    "detail": "Tenant names are PII encrypted under the tenant record and crypto-shredded on tenant destroy\n`tenant.name` is now `personal: { of: \"id\" }`, so it is stored as `kumiko-pii:` ciphertext in events and in `read_tenants`. Signup no longer writes the email into the tenant name; it uses the generated tenant key. The tenant destroy job erases the tenant record key and purges the tenant's search documents. The tenant queries (`me`, memberships, tenant-directory, user list, cap-overview, tenants-missing-profile) decrypt the name, and the tenant list sorts by `key` because encrypted names are not sortable.",
+    "migration": "After the bump run the PII backfill (backfillEventPiiEncryption), then rebuild the read_tenants projection; the backfill only encrypts event payloads. Raw reads of read_tenants.name in apps now return ciphertext and must go through decryptStoredPii or the tenant query handlers. Tenants that were already destroyed (read_tenants.destroyed_at set) get the erased sentinel instead of a fresh record key."
+  },
   {
     "version": "0.341.0",
     "type": "improvement",

package/packages/bundled-features/src/tenant/decrypt-tenant-names.ts

@@ -0,0 +1,17 @@
+import { decryptStoredPii, mapWithConcurrency } from "../shared/index.js";
+
+// Bounded like tenant:query:members: each decrypt hits the KMS adapter's small pool.
+const KMS_POOL_CONCURRENCY = 4;
+
+// Raw reads of read_tenants return the stored column, which is ciphertext
+// under an active KMS; executor reads (crud.list/detail) decrypt on their own.
+export async function decryptTenantNames<T extends { readonly name?: unknown }>(
+  rows: readonly T[],
+  fallbackRequestId: string,
+): Promise<T[]> {
+  return mapWithConcurrency(rows, KMS_POOL_CONCURRENCY, async (row) =>
+    typeof row.name === "string"
+      ? { ...row, name: await decryptStoredPii(row.name, "name", fallbackRequestId) }
+      : row,
+  );
+}

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

@@ -81,8 +81,15 @@ export function createTenantFeature(options?: TenantFeatureOptions): FeatureDefi
     r.systemScope();
     r.requires("config");
     r.extendsRegistrar(EXT_ASSIGNABLE_ROLE, {});
+    // The elevation guards read the registry, the screens only these options: a role the
+    // server accepts but the screen omits is silently stripped on the next member-roles save.
     r.bootCheck(({ features }) => {
-      collectAssignableAppRoles(features);
+      for (const [role, assignableFrom] of collectAssignableAppRoles(features)) {
+        if (options?.assignableAppRoles?.get(role) === assignableFrom) continue;
+        throw new Error(
+          `[tenant] assignable app role "${role}" (assignableFrom "${assignableFrom}") is declared but missing from the tenant screens' options; pass assignableAppRoles: collectAssignableAppRoles(appFeatures) to createTenantFeature.`,
+        );
+      }
     });
     r.entity("tenant", tenantEntity);
     r.entity("tenant-membership", tenantMembershipEntity);

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

@@ -2,6 +2,7 @@ import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { decryptTenantNames } from "../decrypt-tenant-names.js";
 import { tenantTable } from "../schema/tenant.js";
 
 // Direct query — query handlers don't have a tenant-crud handle. A direct
@@ -33,6 +34,8 @@ export const meQuery = defineQueryHandler({
     }
     const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
     const row = await fetchOne(db, tenantTable, { id: query.user.tenantId });
-    return row ?? null;
+    if (row === undefined) return null;
+    const [decrypted] = await decryptTenantNames([row], "tenant:me");
+    return decrypted ?? null;
   },
 });

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

@@ -3,6 +3,7 @@ import { defineQueryHandler, SYSTEM_ROLE } from "@cosmicdrift/kumiko-framework/e
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
+import { decryptTenantNames } from "../decrypt-tenant-names.js";
 import { tenantMembershipsTable } from "../membership-table.js";
 import { tenantTable } from "../schema/tenant.js";
 
@@ -32,9 +33,12 @@ export const membershipsQuery = defineQueryHandler({
     // prefix would be indistinguishable). A single IN-batch over all
     // tenantIds instead of fetchOne per membership (#324).
     type TenantRow = { id: unknown; name?: unknown; key?: unknown; isEnabled?: unknown };
-    const tenants = await selectMany<TenantRow>(db, tenantTable, {
-      id: rows.map((row) => row["tenantId"]),
-    });
+    const tenants = await decryptTenantNames(
+      await selectMany<TenantRow>(db, tenantTable, {
+        id: rows.map((row) => row["tenantId"]),
+      }),
+      "tenant:memberships",
+    );
     const tenantById = new Map<unknown, TenantRow>(tenants.map((t) => [t.id, t]));
 
     return rows

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

@@ -6,6 +6,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { decryptTenantNames } from "../decrypt-tenant-names.js";
 import { tenantTable } from "../schema/tenant.js";
 import { isSystemAdmin } from "./is-system-admin.js";
 
@@ -48,7 +49,7 @@ export const tenantDirectoryQuery = definePagedQueryHandler({
       tenants = await selectMany(db, tenantTable, undefined, {
         limit: scanLimit,
         orderBy: [
-          { col: "name", direction: "asc" },
+          { col: "key", direction: "asc" },
           { col: "id", direction: "asc" },
         ],
       });
@@ -57,10 +58,15 @@ export const tenantDirectoryQuery = definePagedQueryHandler({
       const row = await fetchOne(db, tenantTable, { id: query.user.tenantId });
       tenants = row ? [row] : [];
     }
-    const labeled = tenants.map((tenant) => {
-      const id = String(tenant.id);
-      return { id, label: typeof tenant.name === "string" ? tenant.name : id };
-    });
+    // name is ciphertext at rest, so the SQL page is keyed by the plaintext
+    // `key`; label order and search happen in memory after decrypting.
+    const decrypted = await decryptTenantNames(tenants, "tenant:tenant-directory");
+    const labeled = decrypted
+      .map((tenant) => {
+        const id = String(tenant.id);
+        return { id, label: typeof tenant.name === "string" ? tenant.name : id };
+      })
+      .sort((a, b) => a.label.localeCompare(b.label) || a.id.localeCompare(b.id));
     const needle = search?.toLowerCase();
     const rows =
       needle === undefined

package/packages/bundled-features/src/tenant/handlers/toggle-enabled.write.ts

@@ -14,6 +14,8 @@ function createToggleTenantHandler(enable: boolean) {
     name: verbName,
     schema: z.object({ id: z.uuid() }),
     access: { roles: ["SystemAdmin"] },
+    // Disabling locks every member out; enabling is its undo.
+    ...(enable ? {} : { agent: { risk: "high" as const } }),
     description: enable
       ? "Re-enables a disabled tenant so its members can sign in and switch to it again; this is the undo for tenant:write:disable."
       : "Marks a tenant disabled so it stops counting as a membership — its members can no longer sign in to it or switch to it — while leaving all of its data in place.",

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

@@ -72,6 +72,7 @@ export const updateMemberRolesWrite = defineWriteHandler({
   access: { roles: ["system", ...access.admin] },
   description:
     "Sets the roles a user holds in a tenant, rejecting reserved role names and any grant that would raise the target above the caller; roles the caller could not grant (platform roles such as DataProtectionOfficer or TenantOwner, undeclared or higher-tier app roles) are kept, only the system user replaces the full list; admins act on their own tenant, SystemAdmins on any.",
+  agent: { risk: "high" },
   handler: async (event, ctx) => {
     if (!ctx.systemDb) {
       throw new InternalError({

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

@@ -7,6 +7,7 @@ export {
   TenantHandlers,
   TenantQueries,
 } from "./constants.js";
+export { decryptTenantNames } from "./decrypt-tenant-names.js";
 export { collectAssignableAppRoles, createTenantFeature } from "./feature.js";
 export type { InvitationStatus } from "./invitation-table.js";
 export {

package/packages/bundled-features/src/tenant/invitation-table.ts

@@ -26,6 +26,7 @@ import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntity,
   createMultiSelectField,
+  createNumberField,
   createSelectField,
   createTextField,
   createTimestampField,
@@ -94,6 +95,11 @@ export const tenantInvitationEntity = createEntity({
       personal: { of: "invitedBy" },
       find: "exact",
     }),
+    // Version of the invitee's membership row when the invitation was issued
+    // (0 = no membership yet). Accept compares it against the current version
+    // to detect a membership decision made after the invite. NULL only on rows
+    // issued before this field existed.
+    membershipVersion: createNumberField({ integer: true, min: 0 }),
     // UI-Anzeige — Wahrheit liegt in Redis-TTL.
     expiresAt: createTimestampField({ required: true }),
   },

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

@@ -3,6 +3,7 @@ import {
   createEventStoreExecutor,
   createTenantDb,
   type DbRunner,
+  type TenantDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import { createSystemUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { ConflictError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
@@ -23,7 +24,13 @@ export type InvitedMembershipOptions = {
   readonly userId: string;
   readonly tenantId: TenantId;
   readonly role: string;
-  readonly invitationIssuedAt: Temporal.Instant;
+  readonly invitation: InvitationIssuance;
+};
+
+export type InvitationIssuance = {
+  readonly membershipVersion: number | null;
+  readonly insertedAt: Temporal.Instant;
+  readonly modifiedAt: Temporal.Instant | null;
 };
 
 type MembershipRow = {
@@ -34,6 +41,21 @@ type MembershipRow = {
   readonly modifiedAt: Temporal.Instant | null;
 };
 
+const MEMBERSHIP_CREATED_VERSION = 1;
+
+// 0 = the user has no membership in the tenant yet.
+export async function membershipVersionOf(
+  db: Pick<TenantDb, "fetchOne">,
+  tenantId: string,
+  userId: string,
+): Promise<number> {
+  const membership = await db.fetchOne<{ readonly version: number }>(tenantMembershipsTable, {
+    tenantId,
+    userId,
+  });
+  return membership?.version ?? 0;
+}
+
 // Add-only, so unlike updateMemberRoles no session revoke or last-TenantAdmin check.
 // Read unfiltered: tenant:query:memberships hides disabled tenants.
 export async function grantInvitedMembershipRole(db: DbRunner, options: InvitedMembershipOptions) {
@@ -54,7 +76,7 @@ export async function grantInvitedMembershipRole(db: DbRunner, options: InvitedM
   }
 
   // A membership decision made after the invitation was issued wins over it.
-  if (isMembershipChangedAfter(existing, options.invitationIssuedAt)) {
+  if (isSupersededByMembership(existing, options.invitation)) {
     return writeFailure(invitationSupersededError());
   }
 
@@ -71,17 +93,28 @@ export async function grantInvitedMembershipRole(db: DbRunner, options: InvitedM
   return grantedMembership(true, roles);
 }
 
-// Resend reuses the invitation row, so its last modification is the latest issuance.
-export function invitationIssuedAt(invitation: {
-  readonly insertedAt: Temporal.Instant;
-  readonly modifiedAt: Temporal.Instant | null;
-}): Temporal.Instant {
-  return invitation.modifiedAt ?? invitation.insertedAt;
-}
-
-function isMembershipChangedAfter(membership: MembershipRow, instant: Temporal.Instant): boolean {
+// The pinned version is the membership's version when the invitation was issued
+// (0 = none yet). A different version now means the membership was decided after
+// the invite. Pin 0: a membership that appeared afterwards is an additive grant
+// only while it is untouched since its creation (version 1). A role change bumps
+// the version above 1 and counts as a decision. A removal in between hard-deletes
+// the row and cancels the invitation (remove-member), so it never reaches this check.
+// Rows issued before the pin existed (null) fall back to wall-clock timestamps,
+// which can misjudge changes within the same millisecond but is all they carry.
+function isSupersededByMembership(
+  membership: MembershipRow,
+  invitation: InvitationIssuance,
+): boolean {
+  if (invitation.membershipVersion !== null) {
+    if (invitation.membershipVersion === 0) {
+      return membership.version > MEMBERSHIP_CREATED_VERSION;
+    }
+    return membership.version !== invitation.membershipVersion;
+  }
+  // Resend reuses the invitation row, so its last modification is the latest issuance.
+  const issuedAt = invitation.modifiedAt ?? invitation.insertedAt;
   const lastChangedAt = membership.modifiedAt ?? membership.insertedAt;
-  return Temporal.Instant.compare(lastChangedAt, instant) > 0;
+  return Temporal.Instant.compare(lastChangedAt, issuedAt) > 0;
 }
 
 function invitationSupersededError(): ConflictError {

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

@@ -28,19 +28,17 @@ export const tenantEntity = createEntity({
     key: createTextField({
       required: true,
       maxLength: 50,
+      sortable: true,
       personal: false,
       reason: "technical_reference",
     }),
-    // Workspace/company display name, not an individual's identity —
-    // same class as the `company.legalName` example in the boot-validator's
-    // own PII-heuristic doc-comment.
+    // 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.
     name: createTextField({
       required: true,
       maxLength: 200,
       searchable: true,
-      sortable: true,
-      personal: false,
-      reason: "is_business_data",
+      personal: { of: "id" },
+      find: "none",
     }),
     isEnabled: createBooleanField({ default: true, filterable: true }),
     // Tenant-destroy lifecycle (tenant-lifecycle feature). Defaults keep

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

@@ -43,7 +43,7 @@ export const tenantListScreen: EntityListScreenDefinition = {
       entityId: "id",
     },
   ],
-  defaultSort: { field: "name", dir: "asc" },
+  defaultSort: { field: "key", dir: "asc" },
   searchable: true,
   access: { roles: ["SystemAdmin"] },
   // Inert until an app navs it (see file header) — no nav area to resolve

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

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "improvement",
+    "title": "Reference fields can opt out of the handover with handover: \"stay\"; boot depth limit and mover share one graph definition",
+    "detail": "ReferenceFieldDef gains handover: \"stay\". An entity that should NOT travel with its host but points at it through a plain reference no longer blocks the claim with entity_not_transferable when that reference field carries handover: \"stay\": the edge is not walked, its rows stay in the source tenant, and the reference crosses the tenant boundary after the handover. Without the opt-out the behaviour is unchanged (entity_not_transferable at claim time). Migration: an entity that should NOT travel with its host: mark the reference field handover: \"stay\" (removing transferable alone does not help once rows exist, the claim still fails). The framework now exports one adjacency definition (resolveEntityTransferAdjacency, reference and parentRef edges, non-transferable intermediate nodes included, handover: \"stay\" respected) that the boot validator's depth limit and the tenant-handover mover both use. Consequence: the boot-time MAX_TRANSFER_DEPTH check now also counts parentRef edges and chains running through non-transferable entities, as the mover always did; a graph that was deeper than 5 hops only through such nodes now fails the boot instead of the claim."
+  },
+  {
+    "version": "0.353.0",
+    "type": "fix",
+    "title": "Tenant handover claims fail with transfer_graph_too_deep only when rows exist beyond the last allowed hop",
+    "detail": "Tenant handover only fails with `transfer_graph_too_deep` when rows really hang below the fifth hop, and failed workflow runs report the suspended step\nA claim used to fail whenever the last round's entity type had outgoing edges, even with no rows behind them, so a chain of exactly five hops with an unrestricted `parentRef` entity registered was rejected. `workflow.run-failed` carries the real `stepIndex` for the unsupported-suspension case instead of always 0."
+  },
   {
     "version": "0.321.0",
     "type": "improvement",