@cosmicdrift/kumiko-bundled-features 0.64.0 → 0.66.0

package/src/custom-fields/handlers/set-custom-field.write.ts

@@ -1,7 +1,9 @@
+import { buildEntityTable, extractTableName } from "@cosmicdrift/kumiko-framework/db";
 import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { DEFAULT_VALUE_WRITE_ROLES } from "../constants";
+import { setCustomFieldValue } from "../db/queries/projection";
 import { customFieldsFeature } from "../feature";
 import { fieldWriteAccessDeniedRoles, loadFieldDefinition } from "../lib/field-access";
 import { buildCustomFieldValueSchema } from "../lib/value-schema";
@@ -86,15 +88,55 @@ export const setCustomFieldHandler: WriteHandlerDef = {
       }
     }
 
+    // PII (`sensitive: true` definition): self-project the value here —
+    // synchronously, from the in-memory value — exactly like the entity executor
+    // does for sensitive entity fields. The persisted customField.set event then
+    // omits the value, so PII never enters the immutable event log; the existing
+    // user-data-rights strip of the projection erases it durably. Trade-off: a
+    // projection rebuild replays the value-less event and the MSP skips it (see
+    // wire-for-entity), so the value is gone — identical to a sensitive entity
+    // field. The host table isn't known to this generic handler, so resolve it
+    // per-stack via the registry (no module-global state).
+    const sensitive = loaded.field.sensitive === true;
+    if (sensitive) {
+      const entity = ctx.registry.getEntity(payload.entityName);
+      if (!entity) {
+        // Fail closed: without the host table we cannot self-project, and must
+        // NOT fall back to writing the value into the event log.
+        return failUnprocessable("custom_field_host_unresolved", {
+          entityName: payload.entityName,
+        });
+      }
+      // Resolves the same canonical table name the MSP/postQuery use (the table
+      // NAME, not the drizzle object). Holds unless a host entity is wired with
+      // a custom backing table whose name diverges from its definition — rare,
+      // and the MSP path makes the same assumption.
+      const tableName = extractTableName(
+        buildEntityTable(payload.entityName, entity),
+        "custom-fields/set-custom-field",
+      );
+      await setCustomFieldValue(
+        ctx.db.raw,
+        tableName,
+        payload.fieldKey,
+        payload.value,
+        payload.entityId,
+        event.user.tenantId,
+      );
+    }
+
     // Emit customField.set on host-aggregate stream. unsafeAppendEvent
     // (statt strict appendEvent) weil event-type-map keine cross-feature-
     // augmentation für diesen event-typ hat — wir nutzen den qualified
-    // string-namen direkt.
+    // string-namen direkt. Sensitive fields persist a value-less event (the
+    // value was self-projected above and must stay out of the log).
     await ctx.unsafeAppendEvent({
       aggregateId: payload.entityId,
       aggregateType: payload.entityName,
       type: customFieldsFeature.exports.setEvent.name,
-      payload: { fieldKey: payload.fieldKey, value: payload.value },
+      payload: sensitive
+        ? { fieldKey: payload.fieldKey }
+        : { fieldKey: payload.fieldKey, value: payload.value },
     });
 
     return {

package/src/custom-fields/handlers/update-tenant-field.write.ts

@@ -3,6 +3,7 @@ import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/e
 import { fieldDefinitionAggregateId } from "../aggregate-id";
 import { fieldDefinitionExecutor } from "../executor";
 import { buildFieldDefinitionColumns } from "../lib/field-definition-row";
+import { parseSerializedField } from "../lib/parse-serialized-field";
 import { type UpdateFieldPayload, updateFieldPayloadSchema } from "../schemas";
 
 // update-tenant-field — TenantAdmin ersetzt den Stand einer bestehenden
@@ -59,6 +60,22 @@ export const updateTenantFieldHandler: WriteHandlerDef = {
       });
     }
 
+    // `sensitive` is immutable. Flipping it on an existing field would leave a
+    // GDPR hole: a non-sensitive→sensitive switch can't retroactively erase the
+    // values already written to host rows by past sets (set-custom-field only
+    // routes the PII-safe path at write time). To change sensitivity, delete +
+    // re-define (the honest cut — same rationale as the type guard above).
+    const currentSensitive = parseSerializedField(existing["serializedField"])?.sensitive === true;
+    const requestedSensitive = payload.serializedField.sensitive === true;
+    if (currentSensitive !== requestedSensitive) {
+      return failUnprocessable("field_sensitive_immutable", {
+        entityName: payload.entityName,
+        fieldKey: payload.fieldKey,
+        currentSensitive,
+        requestedSensitive,
+      });
+    }
+
     // entityName/fieldKey sind die Identität — nicht Teil der changes.
     const {
       entityName: _entityName,

package/src/custom-fields/lib/define-or-resurrect.ts

@@ -0,0 +1,52 @@
+import { fieldDefinitionExecutor } from "../executor";
+import type { FieldDefinitionColumns } from "./field-definition-row";
+
+type DefineUser = Parameters<typeof fieldDefinitionExecutor.create>[1];
+type DefineDb = Parameters<typeof fieldDefinitionExecutor.create>[2];
+type WriteResult = Awaited<ReturnType<typeof fieldDefinitionExecutor.create>>;
+
+// Resurrection-aware define for the deterministic fieldDefinition aggregate-id.
+//
+// A definition's id is uuidv5(tenant|entity|fieldKey), so deleting it leaves a
+// (created+deleted) event stream under that id. A plain create() appends at
+// version 0 onto that stream → version_conflict — the deleted (entity, fieldKey)
+// could never be re-defined. The lifecycle states and their handling:
+//   - active definition exists → let create() raise the natural version_conflict
+//     (409) the dedup contract relies on.
+//   - soft-deleted definition  → restore() the stream, then update() it to the
+//     new payload (the caller is defining it afresh).
+//   - never defined            → create().
+//
+// restore-before-create matters: a create() version_conflict aborts the
+// surrounding tx, so a follow-up restore()/update() on the same connection would
+// fail with "current transaction is aborted". detail() (a read) + restore()
+// (which sees soft-deleted rows via selectMany and only writes on success) keep
+// the tx clean until the single terminal write.
+export async function defineOrResurrectFieldDefinition(
+  aggregateId: string,
+  columns: FieldDefinitionColumns,
+  user: DefineUser,
+  db: DefineDb,
+): Promise<WriteResult> {
+  const active = await fieldDefinitionExecutor.detail({ id: aggregateId }, user, db);
+  if (active) {
+    return fieldDefinitionExecutor.create({ id: aggregateId, ...columns }, user, db);
+  }
+
+  const restored = await fieldDefinitionExecutor.restore({ id: aggregateId }, user, db);
+  if (restored.isSuccess) {
+    // restore() just un-deleted the row in this same tx; no concurrent writer
+    // exists, so skip the optimistic-lock version match (we'd otherwise have to
+    // thread the post-restore stream version through). Overwrite with the new
+    // definition payload — the caller is defining the field afresh.
+    // Spread to a mutable copy: `changes` is Record<string, unknown> and the
+    // readonly FieldDefinitionColumns isn't assignable to it.
+    return fieldDefinitionExecutor.update({ id: aggregateId, changes: { ...columns } }, user, db, {
+      skipOptimisticLock: true,
+    });
+  }
+  if (restored.error.code === "not_found") {
+    return fieldDefinitionExecutor.create({ id: aggregateId, ...columns }, user, db);
+  }
+  return restored;
+}

package/src/custom-fields/web/__tests__/custom-fields-form-section.test.tsx

@@ -334,11 +334,13 @@ describe("CustomFieldsFormSection — boolean/date-Pfade", () => {
       </Wrapper>,
     );
 
-    // boolean rendert als Checkbox — Bestand steckt in checked, nicht value.
-    const input = document.getElementById("custom-field-active") as HTMLInputElement;
-    expect(input.checked).toBe(true);
+    // boolean = vendored Radix-Checkbox → button[role=checkbox], Bestand steckt
+    // in aria-checked (kein natives .checked).
+    const checkbox = document.getElementById("custom-field-active");
+    if (checkbox === null) throw new Error("boolean checkbox not rendered");
+    expect(checkbox.getAttribute("aria-checked")).toBe("true");
 
-    fireEvent.click(input);
+    fireEvent.click(checkbox);
     fireEvent.click(screen.getByTestId("custom-fields-form-save"));
     await Promise.resolve();
     await Promise.resolve();

package/src/custom-fields/wire-for-entity.ts

@@ -97,6 +97,13 @@ export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
         if (event.aggregateType !== entityName) return;
         const payload = event.payload as CustomFieldSetPayload; // @cast-boundary engine-payload
 
+        // skip: sensitive fields self-project in the write handler (see
+        // set-custom-field) and persist a value-less event so PII never enters
+        // the log. Such events arrive here with value === undefined — skipping
+        // is correct both live (the handler already wrote the row) and on replay
+        // (the value is intentionally gone, the accepted rebuild-loss).
+        if (payload.value === undefined) return;
+
         // jsonb_set: setze key auf value. Wenn key noch nicht existiert →
         // wird angelegt (create_missing=true ist default). value muss als
         // jsonb-literal kommen.

package/src/files-provider-s3/__tests__/s3-provider.test.ts

@@ -35,9 +35,9 @@ describe("resolveForcePathStyle", () => {
   });
 });
 
-// virtualHostedStyle ist die Inversion, die createS3Provider an Bun.S3Client
-// durchreicht (#175/2). Der `!` ist die stille Drift-Stelle: kippt er, picken
-// Minio/R2 die falsche URL-Form ohne Compile- oder Runtime-Fehler.
+// virtualHostedStyle is the inversion createS3Provider hands to Bun.S3Client.
+// The `!` is the silent drift point: flip it and Minio/R2 pick the wrong URL
+// form with no compile or runtime error.
 describe("resolveVirtualHostedStyle (inverse of forcePathStyle)", () => {
   const cases: ReadonlyArray<{ name: string; config: S3ProviderConfig }> = [
     { name: "no endpoint + no override", config: baseConfig },
@@ -66,11 +66,10 @@ describe("resolveVirtualHostedStyle (inverse of forcePathStyle)", () => {
   });
 });
 
-// presign ist eine reine lokale Signier-Operation (HMAC, kein Netzwerk) →
-// hermetisch testbar mit Dummy-Credentials. Beweist, dass Bun das
-// contentDisposition-Feld tatsächlich als response-content-disposition-Query-
-// Param signiert (#175/3) — sonst lieferte ein Download den UUID-Key statt des
-// Dateinamens, lautlos.
+// presign is a pure local signing operation (HMAC, no network), so it tests
+// hermetically with dummy credentials. Proves Bun actually signs contentDisposition
+// as the response-content-disposition query param — otherwise a download would
+// silently return the UUID key instead of the filename.
 describe("getSignedUrl contentDisposition", () => {
   const provider = createS3Provider({
     bucket: "b",

package/src/files-provider-s3/s3-provider.ts

@@ -54,10 +54,8 @@ export function resolveForcePathStyle(config: S3ProviderConfig): boolean {
   return config.forcePathStyle ?? config.endpoint !== undefined;
 }
 
-// Bun's `virtualHostedStyle` is the inverse of the AWS-SDK `forcePathStyle`
-// knob this config exposes: path-style ⇔ virtualHostedStyle=false. Exported +
-// tested alongside resolveForcePathStyle because the inversion is exactly the
-// seam that silently breaks Minio/R2 if the `!` ever drifts.
+// Bun's `virtualHostedStyle` is the strict inverse of the `forcePathStyle` knob
+// this config exposes — the seam that silently breaks Minio/R2 if the `!` drifts.
 export function resolveVirtualHostedStyle(config: S3ProviderConfig): boolean {
   return !resolveForcePathStyle(config);
 }

package/src/legal-pages/web/__tests__/client-plugin.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import type { TreeNode } from "@cosmicdrift/kumiko-framework/engine";
+import { legalPagesClient } from "../client-plugin";
+
+// Deckt die drei neuen Migrations-Pfade (advisor-Gap): navId-Attach,
+// no-leak ohne navId, und der Unwrap (Provider emittiert die slug-Folder
+// direkt, NICHT mehr unter einem "Legal"-Wrapper — der App-r.nav-Knoten
+// IST der Container). legal-pages ist fetch-frei → Provider direkt aufrufbar.
+
+function collect(
+  provider: () => (emit: (n: readonly TreeNode[]) => void) => () => void,
+): readonly TreeNode[] {
+  let emitted: readonly TreeNode[] | undefined;
+  const unsub = provider()((nodes) => {
+    emitted = nodes;
+  });
+  unsub();
+  if (emitted === undefined) throw new Error("provider emitted nothing");
+  return emitted;
+}
+
+describe("legalPagesClient", () => {
+  test("ohne navId: kein navProvider (server-only-Consumer leaken keinen Node)", () => {
+    const def = legalPagesClient();
+    expect(def.name).toBe("legal-pages");
+    expect(def.navProviders).toBeUndefined();
+  });
+
+  test("mit navId: Provider hängt unter exakt dieser (pass-through) QN", () => {
+    const navId = "publicstatus:nav:legal";
+    const def = legalPagesClient({ navId });
+    expect(Object.keys(def.navProviders ?? {})).toEqual([navId]);
+  });
+
+  test("Provider unwrappt den Legal-Container: Top-Level sind die slug-Folder", () => {
+    const navId = "publicstatus:nav:legal";
+    const provider = legalPagesClient({ navId }).navProviders?.[navId];
+    if (provider === undefined) throw new Error("provider missing");
+    const emitted = collect(provider);
+
+    // Kein "Legal"-Wrapper mehr — der App-Knoten ist der Container.
+    expect(emitted.some((n) => n.label === "Legal")).toBe(false);
+    expect(emitted.length).toBeGreaterThan(0);
+
+    // Jeder Top-Level-Knoten ist ein slug-Folder mit lang-Leaves, die per
+    // Cross-Link auf text-content:edit zeigen.
+    const folder = emitted[0];
+    expect(Array.isArray(folder?.children)).toBe(true);
+    const langLeaf = Array.isArray(folder?.children) ? folder?.children[0] : undefined;
+    expect(langLeaf?.target?.featureId).toBe("text-content");
+    expect(langLeaf?.target?.action).toBe("edit");
+  });
+});

package/src/legal-pages/web/client-plugin.ts

@@ -63,20 +63,19 @@ const treeProvider: TreeChildrenSubscribe = () => (emit) => {
     });
   }
 
-  emit([
-    {
-      label: "Legal",
-      icon: "folder",
-      state: "filled",
-      children: slugFolders,
-    },
-  ]);
+  // Der App-seitige r.nav-Knoten IST der "Legal"-Container → der Provider
+  // emittiert die slug-Folder direkt darunter.
+  emit(slugFolders);
   return () => {};
 };
 
-export function legalPagesClient(): ClientFeatureDefinition {
+// `navId` = QN des r.nav({ provider: true })-Knotens den die App registriert.
+// Statisch (kein Fetch, keine Entities) → kein SSE-Refresh nötig. Ohne navId:
+// kein Sidebar-Knoten (server-only-Consumer leaken nichts).
+export function legalPagesClient(opts?: { readonly navId?: string }): ClientFeatureDefinition {
+  const navId = opts?.navId;
   return {
     name: "legal-pages",
-    treeProvider,
+    ...(navId !== undefined && { navProviders: { [navId]: treeProvider } }),
   };
 }

package/src/managed-pages/handlers/set.write.ts

@@ -51,20 +51,13 @@ export const setWrite = defineWriteHandler({
       );
     }
     const tenantId = override ?? event.user.tenantId;
-    // Bei Override muss der executor-user-Context auf den ziel-tenant
-    // umgestellt werden, sonst läuft getStreamVersion gegen user.tenantId
-    // statt tenantId → version_conflict trotz vorhandener projection-row.
+    // override: point the executor context at the target tenant, else getStreamVersion runs against user.tenantId → version_conflict.
     const executorUser =
       override !== undefined ? { ...event.user, tenantId: override as TenantId } : event.user; // @cast-boundary engine-bridge
 
-    // ctx.db is tenant-scoped to the EXECUTING user (createTenantDb "tenant"
-    // mode). For a cross-tenant override that scope is wrong on BOTH the
-    // existing-check (blind to the target tenant's projection row → every
-    // re-provision retries as a create → unique_violation) AND the executor's
-    // stream reads (getStreamVersion/loadAggregate filtered to the executor's
-    // tenant → not_found/version_conflict). Re-scope a TenantDb to the resolved
-    // target tenant so reads and writes both land there. Safe: the override
-    // branch is SystemAdmin-gated above.
+    // ctx.db is scoped to the executing user's tenant, wrong for a cross-tenant override
+    // on both the existing-check and the executor's stream reads; re-scope to the target.
+    // Safe: the override branch is SystemAdmin-gated above.
     const scopedDb =
       override !== undefined ? createTenantDb(db.raw, override as TenantId, "tenant") : db; // @cast-boundary engine-bridge
     const existing = await fetchOne<PageRow>(scopedDb, pagesTable, {

package/src/sessions/__tests__/rebuild-survival.integration.test.ts

@@ -0,0 +1,97 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  asRawClient,
+  insertOne,
+  selectMany,
+  updateMany,
+} from "@cosmicdrift/kumiko-framework/bun-db";
+import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createRegistry, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createProjectionStateTable,
+  rebuildProjection,
+} from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  createTestDb,
+  type TestDb,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { Temporal } from "temporal-polyfill";
+import { createSessionsFeature } from "../feature";
+import { userSessionEntity, userSessionTable } from "../schema/user-session";
+
+// read_user_sessions is a hot-path direct-write store: sessionCreator inserts
+// rows and the revoke handlers update them WITHOUT emitting lifecycle events.
+// If the table is registered as an r.entity, the framework makes it a
+// rebuildable implicit projection whose replay finds zero matching events and
+// swaps an EMPTY shadow over the live table — silently wiping every active
+// session on the next projection rebuild (deploy / `schema apply`). #498/#494.
+//
+// Pre-fix both tests are RED: the implicit projection "sessions:projection:
+// user-session-entity" exists and rebuilding it empties read_user_sessions.
+// Post-fix (r.unmanagedTable) the table is no longer a rebuild target.
+
+const IMPLICIT_PROJECTION = "sessions:projection:user-session-entity";
+
+let testDb: TestDb;
+const TENANT: TenantId = testTenantId(1);
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, userSessionEntity, "user-session");
+  await createEventsTable(testDb.db);
+  await createProjectionStateTable(testDb.db);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(
+    "TRUNCATE read_user_sessions, kumiko_events, kumiko_projections RESTART IDENTITY CASCADE",
+  );
+});
+
+// Mirrors createSessionCallbacks().sessionCreator + sessionRevoker: a row
+// written directly on the hot path, then revoked — no events anywhere.
+const SID = "00000000-0000-0000-0000-000000000001";
+
+async function insertRevokedSession(db: DbConnection): Promise<void> {
+  const now = Temporal.Now.instant();
+  await insertOne(db, userSessionTable, {
+    id: SID,
+    tenantId: TENANT,
+    userId: "user-1",
+    createdAt: now,
+    expiresAt: now.add({ milliseconds: 3_600_000 }),
+    ip: "1.2.3.4",
+    userAgent: "test-agent",
+  });
+  await updateMany(db, userSessionTable, { revokedAt: now }, { id: SID, revokedAt: null });
+}
+
+describe("sessions / read_user_sessions survives projection rebuild", () => {
+  test("is NOT registered as a rebuildable implicit projection", () => {
+    const registry = createRegistry([createSessionsFeature()]);
+    expect(registry.getAllProjections().has(IMPLICIT_PROJECTION)).toBe(false);
+  });
+
+  test("direct-written rows (incl. revoked state) survive a rebuild", async () => {
+    await insertRevokedSession(createTenantDb(testDb.db, TENANT));
+
+    const registry = createRegistry([createSessionsFeature()]);
+    // Pre-fix: the implicit projection exists → rebuild swaps an empty shadow
+    // → rows wiped. Post-fix: absent → no rebuild → rows untouched. Either way
+    // a regression (re-adding r.entity) makes this fail.
+    if (registry.getAllProjections().has(IMPLICIT_PROJECTION)) {
+      await rebuildProjection(IMPLICIT_PROJECTION, { db: testDb.db, registry });
+    }
+
+    const rows = await selectMany(testDb.db, userSessionTable, {});
+    expect(rows.length).toBe(1);
+    expect((rows[0] as { revokedAt: unknown }).revokedAt).not.toBeNull();
+  });
+});

package/src/sessions/feature.ts

@@ -1,3 +1,4 @@
+import { buildEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { cleanupJob } from "./handlers/cleanup.job";
 import { listQuery } from "./handlers/list.query";
@@ -22,8 +23,9 @@ export type SessionsFeatureOptions = {
   readonly autoRevokeOnPasswordChange?: SessionMassRevoker;
 };
 
-// The sessions feature registers the userSession entity and the three user-
-// facing handlers (mine/revoke/revoke-all-others). It intentionally does NOT
+// The sessions feature registers the read_user_sessions table (as an
+// unmanaged direct-write store, NOT an r.entity — see below) and the three
+// user-facing handlers (mine/revoke/revoke-all-others). It intentionally does NOT
 // export a sessionCreator/sessionRevoker here — those are produced by
 // `createSessionCallbacks()` at app-setup time and wired into
 // `buildServer({ auth: { ... } })`.
@@ -41,7 +43,18 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
     r.describe(
       "Tracks signed-in clients in the `read_user_sessions` table (one row per JWT, keyed by the `sid`/`jti` claim) and exposes handlers for `mine` (list your sessions), `revoke`, and `revokeAllOthers`. Session creation and revocation on the hot auth path are handled by `createSessionCallbacks()`, wired into `buildServer({ auth: { ... } })` outside the dispatcher; the feature also ships a manual-trigger cleanup job for pruning expired rows and an optional `autoRevokeOnPasswordChange` hook that mass-revokes all sessions for a user whenever their `passwordHash` changes.",
     );
-    r.entity("user-session", userSessionEntity);
+    // read_user_sessions is a hot-path direct-write store: sessionCreator
+    // inserts and the revoke handlers update rows WITHOUT emitting lifecycle
+    // events (the row columns ARE the audit trail). Registering it as
+    // r.entity would make it a rebuildable implicit projection whose replay
+    // finds zero session events and swaps an empty shadow over the live
+    // table — wiping every active session on the next projection rebuild
+    // (#498/#494). r.unmanagedTable keeps the migration DDL but opts the
+    // table out of implicit rebuild, like jobs/channel-in-app/feature-toggles
+    // which are direct-write stores too.
+    r.unmanagedTable(buildEntityTableMeta("user-session", userSessionEntity), {
+      reason: "read_side.user_sessions_direct_write",
+    });
 
     const handlers = {
       revoke: r.writeHandler(revokeWrite),

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

@@ -82,9 +82,11 @@ async function listAssignments(
   return res.rows;
 }
 
+// Active assignments only — remove soft-deletes (the stream is kept so a
+// re-assign can restore it), so isDeleted=true rows must not count as assigned.
 async function countAssignments(tenantId: string): Promise<number> {
   const rows = await asRawClient(stack.db).unsafe(
-    "SELECT count(*)::int AS n FROM read_tag_assignments WHERE tenant_id = $1",
+    "SELECT count(*)::int AS n FROM read_tag_assignments WHERE tenant_id = $1 AND is_deleted = FALSE",
     [tenantId],
   );
   return (rows as ReadonlyArray<{ n: number }>)[0]?.n ?? 0;
@@ -165,6 +167,33 @@ describe("tags integration — idempotency", () => {
     await remove(tagId, "credit", "credit-7");
     expect(await countAssignments(admin.tenantId)).toBe(0);
   });
+
+  test("assign → remove → assign-again resurrects the same deterministic stream", async () => {
+    const tagId = await createTag("recurring");
+    await assign(tagId, "credit", "credit-r");
+    await remove(tagId, "credit", "credit-r");
+    expect(await countAssignments(admin.tenantId)).toBe(0);
+
+    // Re-attaching the same (tag, entity) must succeed (restore), not 409 — the
+    // deterministic aggregate-id reuses the removed stream.
+    await assign(tagId, "credit", "credit-r");
+    expect(await countAssignments(admin.tenantId)).toBe(1);
+    const rows = await listAssignments({ field: "entityId", op: "eq", value: "credit-r" });
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.["tagId"]).toBe(tagId);
+  });
+});
+
+describe("tags integration — referential integrity", () => {
+  test("assigning an unknown tagId is rejected (no dangling assignment)", async () => {
+    const err = await stack.http.writeErr(
+      TagsHandlers.assignTag,
+      { tagId: "00000000-0000-4000-8000-00000000dead", entityType: "credit", entityId: "credit-x" },
+      admin,
+    );
+    expect(err.httpStatus).toBe(404);
+    expect(await countAssignments(admin.tenantId)).toBe(0);
+  });
 });
 
 describe("tags integration — multi-tenant isolation", () => {

package/src/tags/entity.ts

@@ -21,11 +21,19 @@ export const tagEntity = createEntity({
 // (tenantId, tagId, entityType, entityId) — see aggregate-id.ts — so there is
 // exactly one row per (tag, entity) and assign is idempotent.
 //
+// softDelete is required, NOT cosmetic: the aggregate-id is deterministic, so
+// removing a tag leaves a (created+deleted) event stream behind under that id.
+// A hard delete would force the next assign to create() at version 0 onto that
+// existing stream → version_conflict (the same tag could never be re-attached).
+// With softDelete the assign handler resurrects the stream via restore(); the
+// list query filters isDeleted, so removed assignments stay hidden.
+//
 // Cross-entity views compose in the read-layer (no JOIN):
 //   - tags of an entity   → list assignments filter { field: "entityId", op: "eq" }
 //   - entities with a tag  → list assignments filter { field: "tagId",   op: "eq" }
 export const tagAssignmentEntity = createEntity({
   table: "read_tag_assignments",
+  softDelete: true,
   fields: {
     tagId: createTextField({ required: true, maxLength: 64 }),
     entityType: createTextField({ required: true, maxLength: 64 }),

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

@@ -1,17 +1,25 @@
 import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { tagAssignmentAggregateId } from "../aggregate-id";
 import { DEFAULT_TAG_ACCESS } from "../constants";
-import { tagAssignmentExecutor } from "../executor";
+import { tagAssignmentExecutor, tagExecutor } from "../executor";
 import { type AssignTagPayload, assignTagPayloadSchema } from "../schemas";
 
 // assign-tag — links a tag to a host entity by (entityType, entityId). The
 // assignment id is deterministic, so the row is unique per (tag, entity).
 //
-// Idempotency: a re-assign hits the existing stream and would version_conflict,
-// which leaves the transaction aborted — so we pre-check existence and return
-// success when the assignment is already present (the requested end state). A
-// concurrent first-time race still version_conflicts (409); acceptable, since
+// Idempotency over the full lifecycle (assign → remove → assign):
+//   - already active        → return success (requested end state).
+//   - removed (soft-deleted) → restore() the existing stream. create() would
+//     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.
+//
+// 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
+// with an unknown tagId would otherwise project a dangling assignment.
 export function createAssignTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
   return {
     name: "assign-tag",
@@ -31,6 +39,13 @@ export function createAssignTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS):
         return { isSuccess: true as const, data: { id } };
       }
 
+      const restored = await tagAssignmentExecutor.restore({ id }, event.user, ctx.db);
+      if (restored.isSuccess) return restored;
+      if (restored.error.code !== "not_found") return restored;
+
+      const tag = await tagExecutor.detail({ id: payload.tagId }, event.user, ctx.db);
+      if (!tag) return writeFailure(new NotFoundError("tag", payload.tagId));
+
       return tagAssignmentExecutor.create(
         {
           id,