@cosmicdrift/kumiko-bundled-features 0.2.2 → 0.3.0

package/src/secrets/__tests__/require-secrets-context.test.ts

@@ -0,0 +1,81 @@
+// requireSecretsContext-Surface-Tests (S2.U3 Atom 3b.fix2).
+//
+// Pinst dass `requireSecretsContext` mit dem schmalen FileProviderContext-
+// Surface funktioniert — nicht nur mit voller HandlerContext.
+// Regression-Pin fuer den latenten Worker-Pfad-Bug:
+//   - Vor 3b.fix wurde `ctx as unknown as HandlerContext` durchgereicht
+//   - Im Worker-Pfad ist `ctx._userId` undefined (dispatcher setzt es nur
+//     im request-Pfad), also throw `_userId missing`
+//   - Fix: Worker-Wrap setzt explizit `_userId: SYSTEM_USER_ID`
+//
+// Der Test inszeniert beide Surfaces (HandlerContext-shape via type-assert
+// + FileProviderContext-shape direkt) und prueft dass beide den happy-path
+// + den fehlt-_userId-throw durchlaufen.
+
+import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-framework/engine";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { describe, expect, test, vi } from "vitest";
+import { requireSecretsContext } from "../feature";
+
+function makeRawSecretsContext(): SecretsContext {
+  return {
+    get: vi.fn(),
+    set: vi.fn(),
+    delete: vi.fn(),
+  };
+}
+
+describe("requireSecretsContext :: FileProviderContext surface", () => {
+  test("succeeds with secrets + _userId present (Worker-Pfad mit SYSTEM_USER_ID)", () => {
+    const fileProviderCtx = {
+      secrets: makeRawSecretsContext(),
+      _userId: SYSTEM_USER_ID,
+    };
+    expect(() => requireSecretsContext(fileProviderCtx, "test-handler")).not.toThrow();
+  });
+
+  test("throws when _userId is missing (latenter Worker-Bug pre-3b.fix)", () => {
+    // Pinst die Falle die der 3b.fix abfaengt: wenn ein Provider-Plugin
+    // `requireSecretsContext` ruft und der ctx kein _userId hat (z.B. weil
+    // ein r.job-Wrap das vergessen hat zu setzen), faellt es FRUEH mit
+    // einer klaren Fehlermeldung um — nicht silent broken.
+    const fileProviderCtx = {
+      secrets: makeRawSecretsContext(),
+      // _userId absichtlich undefined
+    };
+    expect(() => requireSecretsContext(fileProviderCtx, "test-handler")).toThrow(/_userId missing/);
+  });
+
+  test("throws when secrets is missing (boot-Misconfig)", () => {
+    const fileProviderCtx = {
+      _userId: SYSTEM_USER_ID,
+      // secrets absichtlich undefined
+    };
+    expect(() => requireSecretsContext(fileProviderCtx, "test-handler")).toThrow(
+      /ctx\.secrets missing/,
+    );
+  });
+
+  test("audit-userId reaches secrets.get when call is delegated", async () => {
+    // Pinst den Audit-Pfad: wenn ein Plugin secrets.get(...) aufruft, kommt
+    // _userId als audit.userId ohne Override durch. Das ist der Grund warum
+    // SYSTEM_USER_ID nicht durch einen ad-hoc-magic-string ersetzt werden
+    // darf — sonst wird der Audit-Trail inkonsistent.
+    const raw = makeRawSecretsContext();
+    const ctx = {
+      secrets: raw,
+      _userId: SYSTEM_USER_ID,
+    };
+    const wrapped = requireSecretsContext(ctx, "user-data-rights:run-export-jobs");
+    await wrapped.get(
+      "tenant-x" as Parameters<SecretsContext["get"]>[0],
+      "any-key" as unknown as Parameters<SecretsContext["get"]>[1],
+    );
+    // Erste-Aufruf-args: [tenantId, key, audit-Object]
+    const audit = vi.mocked(raw.get).mock.calls[0]?.[2];
+    expect(audit).toEqual({
+      userId: SYSTEM_USER_ID,
+      handlerName: "user-data-rights:run-export-jobs",
+    });
+  });
+});

package/src/secrets/feature.ts

@@ -1,8 +1,4 @@
-import {
-  defineFeature,
-  type FeatureDefinition,
-  type HandlerContext,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { deleteWrite } from "./handlers/delete.write";
@@ -24,7 +20,15 @@ export { type StoredEnvelope, type StoredMetadata, tenantSecretsTable } from "./
 // wraps that raw context so every `.get(...)` call auto-includes the
 // current user + handler as audit metadata — feature code can't forget
 // to log the read (silent bypass of audit was the v1 gap).
-export function requireSecretsContext(ctx: HandlerContext, handlerName: string): SecretsContext {
+//
+// Surface bewusst minimal: HandlerContext-Pfade (Set/Delete-Handler) +
+// FileProviderContext-Pfade (S3-Plugin im Worker) liefern dieselben
+// zwei Felder, also reicht die schmale ctx-shape — kein voller
+// HandlerContext-Import noetig.
+export function requireSecretsContext(
+  ctx: { readonly secrets?: SecretsContext; readonly _userId?: string | undefined },
+  handlerName: string,
+): SecretsContext {
   if (!ctx.secrets) {
     throw new InternalError({
       message:

package/src/secrets/handlers/rotate.job.ts

@@ -51,7 +51,7 @@ export type RotateJobResult = {
 };
 
 export const rotateJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
-  const payload = rawPayload as RotateJobPayload;
+  const payload = rawPayload as RotateJobPayload; // @cast-boundary engine-payload
   if (!ctx.masterKeyProvider) {
     throw new InternalError({
       message:
@@ -64,7 +64,7 @@ export const rotateJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> =>
       message: "[secrets:rotate] ctx.db missing — job context requires a database connection.",
     });
   }
-  const db = ctx.db as DbConnection;
+  const db = ctx.db as DbConnection; // @cast-boundary db-operator
   const batchSize = payload.batchSize ?? DEFAULT_BATCH_SIZE;
   const maxFailures = payload.maxFailures ?? DEFAULT_MAX_FAILURES;
   const deadline = payload.maxDurationMs

package/src/sessions/constants.ts

@@ -5,6 +5,10 @@ export const SESSIONS_FEATURE = "sessions" as const;
 export const SessionHandlers = {
   revoke: "sessions:write:user-session:revoke",
   revokeAllOthers: "sessions:write:user-session:revoke-all-others",
+  /** Privileged: System-Caller (cross-feature) revokes ALL live sessions
+   *  fuer einen User. Genutzt von user-data-rights:restrict-account
+   *  (DSGVO Art. 18 Account-Freeze). */
+  revokeAllForUser: "sessions:write:user-session:revoke-all-for-user",
 } as const;
 
 export const SessionQueries = {

package/src/sessions/feature.ts

@@ -3,6 +3,7 @@ import { cleanupJob } from "./handlers/cleanup.job";
 import { listQuery } from "./handlers/list.query";
 import { mineQuery } from "./handlers/mine.query";
 import { revokeWrite } from "./handlers/revoke.write";
+import { revokeAllForUserWrite } from "./handlers/revoke-all-for-user.write";
 import { revokeAllOthersWrite } from "./handlers/revoke-all-others.write";
 import { userSessionEntity } from "./schema/user-session";
 import type { SessionMassRevoker } from "./session-callbacks";
@@ -42,7 +43,9 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
     const handlers = {
       revoke: r.writeHandler(revokeWrite),
       revokeAllOthers: r.writeHandler(revokeAllOthersWrite),
+      revokeAllForUser: r.writeHandler(revokeAllForUserWrite),
     };
+    r.exposesApi("sessions.revokeAllForUser");
 
     const queries = {
       mine: r.queryHandler(mineQuery),

package/src/sessions/handlers/cleanup.job.ts

@@ -39,13 +39,13 @@ export type SessionCleanupResult = {
 };
 
 export const cleanupJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
-  const payload = rawPayload as SessionCleanupPayload;
+  const payload = rawPayload as SessionCleanupPayload; // @cast-boundary engine-payload
   if (!ctx.db) {
     throw new InternalError({
       message: "[sessions:cleanup] ctx.db missing — job context requires a database connection.",
     });
   }
-  const db = ctx.db as DbConnection;
+  const db = ctx.db as DbConnection; // @cast-boundary db-operator
 
   // Coerce-and-validate: BullMQ payloads arrive as opaque JSON, so TS types
   // don't survive. Guard before the value is interpolated into SQL.

package/src/sessions/handlers/revoke-all-for-user.write.ts

@@ -0,0 +1,42 @@
+import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { and, eq, isNull } from "drizzle-orm";
+import { Temporal } from "temporal-polyfill";
+import { z } from "zod";
+import { userSessionTable } from "../schema/user-session";
+
+// Mass-revoke ALL live sessions for a target user — privileged-only.
+// Used by user-data-rights:restrict-account zur Account-Freeze
+// (DSGVO Art. 18) sowie potenziell anderen ops-flows ("ban user",
+// "compromised account"). Im Gegensatz zu revoke-all-others wird
+// die ggf. aufrufende Session ebenfalls revoked — Caller ist System
+// (cron/operator/cross-feature), nicht der Endnutzer selbst.
+//
+// Tenant-scope: das userSession-Schema persistiert tenantId pro Row
+// (User kann mehrere Sessions in mehreren Tenants haben). Wir
+// revoken cross-tenant, weil "Account-Restriction" eine globale
+// User-Aussage ist (Forget-Pfad ist auch global, sieht User-Entity-
+// special-Doc). UPDATE filtert nur auf userId.
+export const revokeAllForUserWrite = defineWriteHandler({
+  name: "user-session:revoke-all-for-user",
+  schema: z.object({
+    userId: z.string().min(1),
+  }),
+  access: { roles: access.privileged },
+  handler: async (event, ctx) => {
+    const updated = await ctx.db.raw
+      .update(userSessionTable)
+      .set({ revokedAt: Temporal.Now.instant() })
+      .where(
+        and(
+          eq(userSessionTable["userId"], event.payload.userId),
+          isNull(userSessionTable["revokedAt"]),
+        ),
+      )
+      .returning();
+
+    return {
+      isSuccess: true as const,
+      data: { count: updated.length, userId: event.payload.userId },
+    };
+  },
+});

package/src/step-dispatcher/feature.ts

@@ -0,0 +1,62 @@
+// step-dispatcher — bundled-feature that drains deferred Tier-2 step
+// requests (webhook.send, mail.send, ...) after their TX commits.
+//
+// Listens on the `kumiko:system:step.dispatch-requested` system event
+// (registry-bypassed, see append-event-core.ts SYSTEM_EVENT_PREFIX).
+// Performs the side-effect and emits `kumiko:system:step.dispatched`
+// or `kumiko:system:step.dispatch-failed` back onto the same stream so
+// the audit trail lives in the event log only — no separate status table.
+
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type MailSpec, performMailDispatch } from "./mail-runner";
+import { performWebhookDispatch, type WebhookSpec } from "./webhook-runner";
+
+export const STEP_DISPATCH_AGGREGATE_TYPE = "step-dispatch";
+export const STEP_DISPATCH_REQUESTED_TYPE = "kumiko:system:step.dispatch-requested";
+export const STEP_DISPATCHED_TYPE = "kumiko:system:step.dispatched";
+export const STEP_DISPATCH_FAILED_TYPE = "kumiko:system:step.dispatch-failed";
+
+type DispatchRequestedPayload =
+  | {
+      readonly stepKind: "webhook.send";
+      readonly spec: WebhookSpec;
+      readonly retry?: { readonly times: number; readonly backoff: "exponential" | "linear" };
+    }
+  | {
+      readonly stepKind: "mail.send";
+      readonly spec: MailSpec;
+    };
+
+export function createStepDispatcherFeature(): FeatureDefinition {
+  return defineFeature("step-dispatcher", (r) => {
+    r.systemScope();
+
+    r.multiStreamProjection({
+      name: "step-dispatcher",
+      apply: {
+        [STEP_DISPATCH_REQUESTED_TYPE]: async (event, _tx, ctx) => {
+          const payload = event.payload as DispatchRequestedPayload;
+          const result =
+            payload.stepKind === "webhook.send"
+              ? await performWebhookDispatch(payload.spec)
+              : await performMailDispatch(payload.spec);
+          if (result.ok) {
+            await ctx.unsafeAppendEvent({
+              aggregateId: event.aggregateId,
+              aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
+              type: STEP_DISPATCHED_TYPE,
+              payload: { stepKind: payload.stepKind, status: result.status },
+            });
+          } else {
+            await ctx.unsafeAppendEvent({
+              aggregateId: event.aggregateId,
+              aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
+              type: STEP_DISPATCH_FAILED_TYPE,
+              payload: { stepKind: payload.stepKind, error: result.error, attempt: 1 },
+            });
+          }
+        },
+      },
+    });
+  });
+}

package/src/step-dispatcher/index.ts

@@ -0,0 +1,16 @@
+export { createStepDispatcherFeature, STEP_DISPATCH_AGGREGATE_TYPE } from "./feature";
+export {
+  type MailDispatchResult,
+  type MailSpec,
+  mailSpecSchema,
+  performMailDispatch,
+  setMailRunner,
+} from "./mail-runner";
+export {
+  performWebhookDispatch,
+  setWebhookFetch,
+  setWebhookSecretResolver,
+  type WebhookDispatchResult,
+  type WebhookSpec,
+  webhookSpecSchema,
+} from "./webhook-runner";

package/src/step-dispatcher/mail-runner.ts

@@ -0,0 +1,32 @@
+// Mail execution logic — separated from feature.ts and tests-injectable.
+// Production wiring (mail-foundation transport) is a follow-up; the
+// default impl throws so a missing setMailRunner is loud, not silent.
+
+import { z } from "zod";
+
+export const mailSpecSchema = z.object({
+  to: z.union([z.string(), z.array(z.string())]),
+  subject: z.string(),
+  body: z.string(),
+  from: z.string().optional(),
+});
+
+export type MailSpec = z.infer<typeof mailSpecSchema>;
+
+export type MailDispatchResult =
+  | { readonly ok: true; readonly status: number }
+  | { readonly ok: false; readonly error: string };
+
+let mailRunner: (spec: MailSpec) => Promise<MailDispatchResult> = async () => ({
+  ok: false,
+  error:
+    "no mail-runner configured — call setMailRunner() with a mail-foundation transport adapter",
+});
+
+export function setMailRunner(fn: (spec: MailSpec) => Promise<MailDispatchResult>): void {
+  mailRunner = fn;
+}
+
+export async function performMailDispatch(spec: MailSpec): Promise<MailDispatchResult> {
+  return mailRunner(spec);
+}

package/src/step-dispatcher/webhook-runner.ts

@@ -0,0 +1,67 @@
+// Webhook execution logic — separated from feature.ts so tests can stub
+// the fetch without touching the MSP wiring.
+
+import { z } from "zod";
+
+export const webhookSpecSchema = z.object({
+  url: z.string(),
+  method: z.enum(["POST", "PUT", "PATCH"]),
+  headers: z.record(z.string(), z.string()),
+  body: z.unknown().optional(),
+  auth: z
+    .union([
+      z.object({ kind: z.literal("bearer"), secretRef: z.string() }),
+      z.object({ kind: z.literal("header"), name: z.string(), secretRef: z.string() }),
+    ])
+    .optional(),
+});
+
+export type WebhookSpec = z.infer<typeof webhookSpecSchema>;
+
+export type WebhookDispatchResult =
+  | { readonly ok: true; readonly status: number }
+  | { readonly ok: false; readonly error: string };
+
+// Resolves a secretRef via the test-injectable secret-store. Default
+// implementation reads from process.env at the prefix WEBHOOK_SECRET_.
+// Tests pass a custom resolver via setWebhookSecretResolver.
+let secretResolver: (ref: string) => string | undefined = (ref) =>
+  process.env[`WEBHOOK_SECRET_${ref}`];
+
+export function setWebhookSecretResolver(fn: (ref: string) => string | undefined): void {
+  secretResolver = fn;
+}
+
+let fetchImpl: typeof fetch = globalThis.fetch.bind(globalThis);
+
+export function setWebhookFetch(fn: typeof fetch): void {
+  fetchImpl = fn;
+}
+
+export async function performWebhookDispatch(spec: WebhookSpec): Promise<WebhookDispatchResult> {
+  const headers: Record<string, string> = { "content-type": "application/json", ...spec.headers };
+  if (spec.auth) {
+    const secret = secretResolver(spec.auth.secretRef);
+    if (!secret) {
+      return { ok: false, error: `secret "${spec.auth.secretRef}" not configured` };
+    }
+    if (spec.auth.kind === "bearer") {
+      headers["authorization"] = `Bearer ${secret}`;
+    } else {
+      headers[spec.auth.name] = secret;
+    }
+  }
+  try {
+    const res = await fetchImpl(spec.url, {
+      method: spec.method,
+      headers,
+      body: spec.body !== undefined ? JSON.stringify(spec.body) : undefined,
+    });
+    if (!res.ok) {
+      return { ok: false, error: `HTTP ${res.status}: ${res.statusText}` };
+    }
+    return { ok: true, status: res.status };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}

package/src/subscription-mollie/plugin-methods.ts

@@ -66,7 +66,7 @@ export function createMollieCheckoutSession(
         tenantId: options.tenantId,
         priceId: options.priceId,
       },
-    }) as Promise<Payment>)) satisfies Payment;
+    }) as Promise<Payment>)) satisfies Payment; // @cast-boundary engine-bridge
 
     const checkoutHref = payment.getCheckoutUrl();
     if (!checkoutHref) {

package/src/subscription-mollie/verify-webhook.ts

@@ -102,7 +102,7 @@ export function verifyAndParseMollieWebhook(
       return null;
     }
 
-    const metadata = (subscription.metadata as Record<string, string> | null) ?? {};
+    const metadata = (subscription.metadata as Record<string, string> | null) ?? {}; // @cast-boundary engine-bridge
     const tenantId = metadata["tenantId"];
     if (!tenantId || tenantId.length === 0) return null;
     const priceId = metadata["priceId"];
@@ -153,7 +153,7 @@ async function ensureSubscriptionForMandate(
 ): Promise<MollieSubscription | null> {
   const customerId = payment.customerId;
   if (!customerId) return null;
-  const paymentMetadata = (payment.metadata as Record<string, string> | null) ?? {};
+  const paymentMetadata = (payment.metadata as Record<string, string> | null) ?? {}; // @cast-boundary engine-bridge
   const tenantId = paymentMetadata["tenantId"];
   const priceId = paymentMetadata["priceId"];
   if (!tenantId || !priceId) return null;
@@ -163,7 +163,7 @@ async function ensureSubscriptionForMandate(
   const existing = await client.customerSubscriptions.list(customerId);
   const matchingExisting = existing.find(
     (sub) =>
-      (sub.metadata as Record<string, string> | null)?.["priceId"] === priceId &&
+      (sub.metadata as Record<string, string> | null)?.["priceId"] === priceId && // @cast-boundary engine-bridge
       (sub.status === "active" || sub.status === "pending"),
   );
   if (matchingExisting) return matchingExisting;
@@ -185,8 +185,12 @@ export function extractMollieId(rawBody: string, headers: Record<string, string>
   const contentType = headers["content-type"] ?? "";
   if (contentType.includes("application/json")) {
     try {
-      const parsed = JSON.parse(rawBody) as { id?: unknown };
-      return typeof parsed.id === "string" ? parsed.id : null;
+      const parsed: unknown = JSON.parse(rawBody);
+      const id =
+        typeof parsed === "object" && parsed !== null && "id" in parsed
+          ? (parsed as Record<string, unknown>)["id"] // @cast-boundary engine-payload
+          : undefined;
+      return typeof id === "string" ? id : null;
     } catch {
       return null;
     }

package/src/subscription-stripe/verify-webhook.ts

@@ -203,15 +203,15 @@ async function extractSubscriptionFromEvent(
     case StripeEventTypes.customerSubscriptionCreated:
     case StripeEventTypes.customerSubscriptionUpdated:
     case StripeEventTypes.customerSubscriptionDeleted:
-      return event.data.object as Stripe.Subscription;
+      return event.data.object as Stripe.Subscription; // @cast-boundary engine-bridge
     case StripeEventTypes.invoicePaid:
     case StripeEventTypes.invoicePaymentFailed: {
       // Lazy-fetch der subscription. invoice.subscription ist eine
       // string-id (Stripe-Webhooks expanden nicht auto). Wir holen das
       // full subscription-Object damit der downstream-mapping
       // (status, tier via priceId, period-end) konsistent funktioniert.
-      const invoice = event.data.object as Stripe.Invoice;
-      const subRef = (invoice as { subscription?: string | Stripe.Subscription | null })
+      const invoice = event.data.object as Stripe.Invoice; // @cast-boundary engine-bridge
+      const subRef = (invoice as { subscription?: string | Stripe.Subscription | null }) // @cast-boundary engine-payload
         .subscription;
       if (!subRef) {
         // Invoice ohne subscription-reference (= one-shot-invoice, nicht

package/src/tenant/handlers/active-tenant-ids.query.ts

@@ -14,6 +14,6 @@ export const activeTenantIdsQuery = defineQueryHandler({
       .from(tenantTable)
       .where(eq(tenantTable["isEnabled"], true));
 
-    return rows.map((row) => (row as DbRow)["id"] as number);
+    return rows.map((row) => (row as DbRow)["id"] as number); // @cast-boundary db-row
   },
 });

package/src/tenant/handlers/cancel-invitation.write.ts

@@ -61,7 +61,7 @@ export const cancelInvitationWrite = defineWriteHandler({
     const updateResult = await executor.update(
       {
         id: event.payload.invitationId,
-        version: invitation["version"] as number,
+        version: invitation["version"] as number, // @cast-boundary db-row
         changes: { status: INVITATION_STATUS.cancelled },
       },
       event.user,

package/src/tenant/handlers/remove-member.write.ts

@@ -31,7 +31,7 @@ export const removeMemberWrite = defineWriteHandler({
     }
 
     const result = await executor.delete(
-      { id: (existing as DbRow)["id"] as string },
+      { id: (existing as DbRow)["id"] as string }, // @cast-boundary db-row
       event.user,
       db,
     );

package/src/tenant/handlers/resolve-user-ids.query.ts

@@ -27,7 +27,7 @@ export const resolveUserIdsQuery = defineQueryHandler({
         .select({ userId: tenantMembershipsTable.userId })
         .from(tenantMembershipsTable)
         .where(eq(tenantMembershipsTable.tenantId, tenantId));
-      return rows.map((r) => r["userId"] as number);
+      return rows.map((r) => r["userId"] as number); // @cast-boundary db-row
     }
 
     if (userId !== undefined) {

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

@@ -39,11 +39,11 @@ export const updateMemberRolesWrite = defineWriteHandler({
     // between this read and append) surfaces as version_conflict rather than
     // silent overwrite. Per-membership parallelism is rare; if it happens,
     // the client retries on the error.
-    const row = existing as DbRow;
+    const row = existing as DbRow; // @cast-boundary generic-record
     const result = await executor.update(
       {
-        id: row["id"] as string,
-        version: row["version"] as number,
+        id: row["id"] as string, // @cast-boundary db-row
+        version: row["version"] as number, // @cast-boundary db-row
         changes: { roles: JSON.stringify(event.payload.roles) },
       },
       event.user,

package/src/text-content/constants.ts

@@ -1,3 +1,4 @@
+// @runtime client
 // Feature name
 export const TEXT_CONTENT_FEATURE = "text-content" as const;
 
@@ -9,6 +10,7 @@ export const TextContentHandlers = {
 // Qualified query handler names (QN format: scope:type:name)
 export const TextContentQueries = {
   bySlug: "text-content:query:by-slug",
+  byTenant: "text-content:query:by-tenant",
 } as const;
 
 // Error codes

package/src/text-content/feature.ts

@@ -1,5 +1,6 @@
-import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { bySlugQuery } from "./handlers/by-slug.query";
+import { byTenantQuery } from "./handlers/by-tenant.query";
 import { setWrite } from "./handlers/set.write";
 import { textBlockEntity } from "./table";
 
@@ -11,8 +12,16 @@ import { textBlockEntity } from "./table";
 //
 // Opt-in: wer keine statischen Texte braucht (interne Tools), aktiviert
 // das Feature gar nicht. Wer es aktiviert, hat sofort CRUD + by-slug-
-// query — Routes/Render kommen pro Use-Case (legal-pages, etc.).
-export function createTextContentFeature(): FeatureDefinition {
+// query + by-tenant-list-query — Routes/Render kommen pro Use-Case
+// (legal-pages, Visual-Tree, etc.).
+//
+// **Visual-Tree-Integration (V.1.2)**: r.treeActions deklariert die
+// Edit-Actions für Cross-Feature-Linking via buildTarget. Der Handle
+// wird via setup-export propagiert (Memory `[EventDef-Exports-Pattern]`),
+// sodass andere Features compile-time-typed Cross-Feature-Edits triggern
+// können — siehe legal-pages's TreeProvider der text-content:edit als
+// Target nutzt. Der Client-side TreeProvider lebt in `web/client-plugin.ts`.
+export function createTextContentFeature() {
   return defineFeature("text-content", (r) => {
     r.entity("text-block", textBlockEntity);
 
@@ -22,8 +31,15 @@ export function createTextContentFeature(): FeatureDefinition {
 
     const queries = {
       bySlug: r.queryHandler(bySlugQuery),
+      byTenant: r.queryHandler(byTenantQuery),
     };
 
-    return { handlers, queries };
+    const treeHandle = r.treeActions({
+      edit: { args: { slug: "" as string, lang: "" as string } },
+      list: {},
+      create: { args: { folder: "" as string } },
+    });
+
+    return { handlers, queries, treeHandle };
   });
 }

package/src/text-content/handlers/by-tenant.query.ts

@@ -0,0 +1,56 @@
+import { castTenantRows } from "@cosmicdrift/kumiko-framework/db";
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { AccessDeniedError } from "@cosmicdrift/kumiko-framework/errors";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { type TextBlockRow, textBlocksTable } from "../table";
+
+// Public-Read aller Text-Blocks für einen Tenant. Use-Case: Visual-Tree-
+// Provider lädt die Slug-Liste zur Sidebar-Render. Anonymous: explizit
+// in roles damit no-JWT-Visitors auch lesen können (Marketing-Sidebar
+// auf Public-Pages). Tenant-Scope kommt aus query.user.tenantId; optional
+// `tenantIdOverride` (SystemAdmin-only) — symmetrisch zu by-slug.query.
+//
+// **Listing statt single-row**: anders als by-slug returnt das hier
+// `{ blocks: [...] }` mit allen Slugs des Tenants. Pro Slug nur die
+// Summary-Felder (kein full body — den lädt der Editor on-demand via
+// by-slug). Hält die Sidebar-Payload klein bei vielen Slugs.
+export type TextBlockSummary = {
+  readonly slug: string;
+  readonly lang: string;
+  readonly title: string;
+  readonly body: string | null;
+  readonly updatedAt: Date;
+};
+
+export const byTenantQuery = defineQueryHandler({
+  name: "by-tenant",
+  schema: z.object({
+    /** Optional cross-tenant read — nur für SystemAdmin. Symmetrisch
+     *  zur by-slug.query und set.write Override-Logik. */
+    tenantIdOverride: z.string().min(1).optional(),
+  }),
+  access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
+  handler: async (query, ctx) => {
+    const override = query.payload.tenantIdOverride;
+    if (override !== undefined && !query.user.roles.includes("SystemAdmin")) {
+      throw new AccessDeniedError({
+        i18nKey: "textContent.errors.tenantOverrideRequiresSystemAdmin",
+        details: { reason: "tenant_override_requires_system_admin" },
+      });
+    }
+    const tenantId = override ?? query.user.tenantId;
+    const rows = castTenantRows<TextBlockRow>(
+      await ctx.db.select().from(textBlocksTable).where(eq(textBlocksTable["tenantId"], tenantId)),
+    );
+    return {
+      blocks: rows.map((row) => ({
+        slug: row.slug,
+        lang: row.lang,
+        title: row.title,
+        body: row.body,
+        updatedAt: row.updatedAt,
+      })),
+    };
+  },
+});

package/src/text-content/handlers/set.write.ts

@@ -68,7 +68,7 @@ export const setWrite = defineWriteHandler({
     // Symmetrisch zu seedTextBlock, das TestUsers.systemAdmin (tenantId =
     // SYSTEM_TENANT) als by verwendet.
     const executorUser =
-      override !== undefined ? { ...event.user, tenantId: override as TenantId } : event.user;
+      override !== undefined ? { ...event.user, tenantId: override as TenantId } : event.user; // @cast-boundary engine-bridge
 
     const existing = await fetchOne<TextBlockRow>(
       db,