@cosmicdrift/kumiko-framework 0.70.0 → 0.71.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.70.0",
+  "version": "0.71.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.70.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.71.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/schema-cli-rebuild.integration.test.ts

@@ -173,4 +173,19 @@ describe("runSchemaCli apply — projection rebuild", () => {
     expect(cap.log.join("\n")).not.toContain("Rebuild");
     expect(await counterFor(group)).toBeUndefined();
   });
+
+  // Marker zeigt auf eine Tabelle die KEINE registrierte Projektion hat →
+  // projections.size === 0 → Early-Return vor dem Rebuild-Schritt (kein Throw,
+  // exit 0). Bisher nur "kein Marker" und "keine Features" getestet.
+  test("with features: marker for a table with no registered projection → no rebuild, exit 0", async () => {
+    await executor.create({ groupId: group, name: "x" }, admin, tdb);
+
+    const appCwd = writeMigration("0004_unknown_table", ["read_nonexistent_table"]);
+    const cap = captureOut();
+    const code = await runSchemaCli(["apply"], appCwd, cap.out, { features: [feature] });
+
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).not.toContain("Rebuild");
+    expect(await counterFor(group)).toBeUndefined();
+  });
 });

package/src/api/auth-middleware.ts

@@ -24,8 +24,10 @@ export type AuthTransport = "cookie" | "bearer";
 
 // Status of a sid from the server's perspective. The sessions feature owns
 // the DB-backed implementation; middleware just consults whatever function
-// the app wires in.
-export type AuthSessionStatus = "live" | "revoked" | "expired" | "missing";
+// the app wires in. "blocked" = sid is live but the user it belongs to is
+// locked (restricted/deleted) — defense-in-depth so a missed session-revoke
+// can't keep a locked account authenticated.
+export type AuthSessionStatus = "live" | "revoked" | "expired" | "missing" | "blocked";
 
 // Called by the middleware after JWT-verify. Gets the sid AND the expected
 // userId from the JWT's `sub` — the checker MUST confirm the session row

package/src/db/__tests__/assert-exists-in.integration.test.ts

@@ -66,6 +66,16 @@ describe("assertExistsIn — DbConnection + explizite tenantId", () => {
     });
     expect(r).toBeInstanceOf(NotFoundError);
   });
+
+  test("zusätzliches where matcht → null (existiert)", async () => {
+    const r = await assertExistsIn(stack.db, orderTable, {
+      field: "id",
+      value: ID_A,
+      tenantId: tenantA,
+      where: { name: "A-Order" },
+    });
+    expect(r).toBeNull();
+  });
 });
 
 describe("assertExistsIn — TenantDb auto-filter", () => {
@@ -79,6 +89,12 @@ describe("assertExistsIn — TenantDb auto-filter", () => {
     const r = await assertExistsIn(dbA, orderTable, { field: "id", value: ID_B });
     expect(r).toBeInstanceOf(NotFoundError);
   });
+
+  test("fehlende Row via TenantDb → NotFoundError", async () => {
+    const dbA = createTenantDb(stack.db, tenantA, "tenant");
+    const r = await assertExistsIn(dbA, orderTable, { field: "id", value: MISSING });
+    expect(r).toBeInstanceOf(NotFoundError);
+  });
 });
 
 describe("assertExistsIn — Fehler-Benennung + where", () => {

package/src/db/__tests__/eagerload.integration.test.ts

@@ -109,6 +109,23 @@ describe("enrichWithReferences", () => {
     expect(single(row, "author")).toBeUndefined();
   });
 
+  // multiple-ref-Contract: IMMER ein Array (gefiltert), nie undefined — anders
+  // als single (oben). Ein Renderer kann auf .map() vertrauen ohne null-Check.
+  test("multiple-ref filtert cross-tenant raus, behält den Rest als Array", async () => {
+    const row = await enrichA({ id: "p1", tags: [A1, BX] });
+    expect(many(row, "tags")?.map((t) => t["name"])).toEqual(["Ada"]);
+  });
+
+  test("multiple-ref nur cross-tenant → [] (leeres Array, NICHT undefined)", async () => {
+    const row = await enrichA({ id: "p1", tags: [BX] });
+    expect(many(row, "tags")).toEqual([]);
+  });
+
+  test("multiple-ref null → [] (leeres Array, NICHT undefined)", async () => {
+    const row = await enrichA({ id: "p1", tags: null });
+    expect(many(row, "tags")).toEqual([]);
+  });
+
   test("TENANT-ISOLATION: cross-tenant-ref wird NICHT aufgelöst", async () => {
     // bx gehört tenantB; dbA ist auf tenantA gescoped → der Lookup filtert
     // ihn raus, _refs bleibt undefined (Renderer fällt auf die UUID zurück).

package/src/db/__tests__/event-store-executor.integration.test.ts

@@ -104,6 +104,20 @@ describe("event-store-executor", () => {
     const detail = await crud.detail({ id: created.data.id }, adminUser, tdb);
     expect(detail).toBeNull();
   });
+
+  test("list hides soft-deleted rows; includeDeleted returns them (trash query)", async () => {
+    const created = await crud.create({ email: "trash@test.de" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+    await crud.delete({ id: created.data.id }, adminUser, tdb);
+
+    const live = await crud.list({}, adminUser, tdb);
+    expect(live.rows.find((r) => r["id"] === created.data.id)).toBeUndefined();
+
+    const trash = await crud.list({}, adminUser, tdb, { includeDeleted: true });
+    const row = trash.rows.find((r) => r["id"] === created.data.id);
+    expect(row).toBeDefined();
+    expect(row?.["isDeleted"]).toBe(true);
+  });
 });
 
 // Sensitive-field stripping: passwords/tokens/IBANs stay in the entity row

package/src/db/event-store-executor.ts

@@ -218,7 +218,14 @@ export type EventStoreExecutor = {
      *  hier zur Runtime einen aus ctx.searchAdapter durchreichen.
      *  options.searchAdapter (build-time) gewinnt — runtime-Override
      *  ist Fallback für die default-Wrapper. */
-    runtimeOptions?: { readonly searchAdapter?: SearchAdapter },
+    runtimeOptions?: {
+      readonly searchAdapter?: SearchAdapter;
+      // Trash query: skip the implicit `isDeleted = FALSE` filter so soft-
+      // deleted rows are returned too. Tenant + ownership clauses still apply
+      // — includeDeleted only relaxes the soft-delete predicate, never the
+      // visibility ones, so it can ride untrusted query input safely.
+      readonly includeDeleted?: boolean;
+    },
   ) => Promise<CursorResult<Record<string, unknown>>>;
 
   detail: (
@@ -862,7 +869,7 @@ export function createEventStoreExecutor(
         params.push(db.tenantId, SYSTEM_TENANT_ID);
         whereSql.push(`${colSql("tenantId")} IN ($${params.length - 1}, $${params.length})`);
       }
-      if (softDelete && table["isDeleted"]) {
+      if (softDelete && table["isDeleted"] && runtimeOptions?.includeDeleted !== true) {
         whereSql.push(`${colSql("isDeleted")} = FALSE`);
       }
       if (payload.cursor) {

package/src/engine/__tests__/boot-validator.test.ts

@@ -2016,6 +2016,7 @@ describe("boot-validator", () => {
   describe("entityList rowAction row-meta allowlist (#331, #323)", () => {
     function makeFeature(opts: {
       pick?: readonly string[];
+      map?: Record<string, string>;
       visibleField?: string;
       softDelete?: boolean;
     }) {
@@ -2038,6 +2039,7 @@ describe("boot-validator", () => {
               label: "actions.archive",
               handler: "shop:write:archive",
               ...(opts.pick ? { payload: { pick: [...opts.pick] } } : {}),
+              ...(opts.map ? { payload: { map: { ...opts.map } } } : {}),
               ...(opts.visibleField ? { visible: { field: opts.visibleField, eq: true } } : {}),
             },
           ],
@@ -2071,6 +2073,16 @@ describe("boot-validator", () => {
       );
     });
 
+    test("map-Extractor mit Base-Column tenantId → kein Throw", () => {
+      expect(() => validateBoot([makeFeature({ map: { target: "tenantId" } })])).not.toThrow();
+    });
+
+    test("map-Extractor mit unknown Field → Throw", () => {
+      expect(() => validateBoot([makeFeature({ map: { target: "ghost" } })])).toThrow(
+        /payload references unknown field "ghost"/,
+      );
+    });
+
     test("softDelete-Entity: pick isDeleted → kein Throw", () => {
       expect(() =>
         validateBoot([makeFeature({ pick: ["id", "isDeleted"], softDelete: true })]),

package/src/engine/__tests__/soft-delete-cleanup.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../define-feature";
+import { createRegistry } from "../registry";
+import {
+  DEFAULT_GRACE_DAYS,
+  SOFT_DELETE_CLEANUP_JOB,
+  SOFT_DELETE_GRACE_DAYS_KEY,
+  softDeleteCleanupJob,
+} from "../soft-delete-cleanup";
+import type { AppContext } from "../types/handlers";
+
+function featureWith(softDelete: boolean | undefined) {
+  return defineFeature("probe-sd", (r) => {
+    r.entity("thing", {
+      fields: { label: { type: "text" } },
+      ...(softDelete !== undefined && { softDelete }),
+    });
+  });
+}
+
+describe("registry soft-delete auto-wiring", () => {
+  test("injects cleanup job + grace-days config when an entity opts into softDelete", () => {
+    const registry = createRegistry([featureWith(true)]);
+    expect(registry.getAllJobs().has(SOFT_DELETE_CLEANUP_JOB)).toBe(true);
+    expect(registry.getAllConfigKeys().has(SOFT_DELETE_GRACE_DAYS_KEY)).toBe(true);
+    const job = registry.getJob(SOFT_DELETE_CLEANUP_JOB);
+    expect(job?.trigger).toEqual({ cron: "0 3 * * *" });
+    expect(job?.perTenant).toBe(true);
+    const key = registry.getConfigKey(SOFT_DELETE_GRACE_DAYS_KEY);
+    expect(key?.type).toBe("number");
+    expect(key?.default).toBe(DEFAULT_GRACE_DAYS);
+  });
+
+  test("does NOT inject when no entity uses softDelete", () => {
+    const registry = createRegistry([featureWith(false)]);
+    expect(registry.getAllJobs().has(SOFT_DELETE_CLEANUP_JOB)).toBe(false);
+    expect(registry.getAllConfigKeys().has(SOFT_DELETE_GRACE_DAYS_KEY)).toBe(false);
+  });
+});
+
+type DeleteCall = { table: unknown; where: Record<string, unknown> };
+
+function makeCtx(opts: { graceDays?: number; calls: DeleteCall[] }): AppContext {
+  // Shaped to satisfy bun-db's tenantDbDelegate() probe so deleteMany() routes
+  // to this recorder instead of trying to extract real table metadata.
+  const fakeDb = {
+    tenantId: "t1",
+    raw: { unsafe: async () => [] },
+    selectMany: async () => [],
+    fetchOne: async () => undefined,
+    insertOne: async () => undefined,
+    updateMany: async () => [],
+    deleteMany: async (table: unknown, where: Record<string, unknown>) => {
+      opts.calls.push({ table, where });
+    },
+  };
+  const projections = new Map<string, unknown>([
+    // softDelete entity WITH a tenantId column → tenant-scoped delete
+    ["thing~impl", { isImplicit: true, source: "thing", table: { tenantId: {}, isDeleted: {} } }],
+    // softDelete entity WITHOUT a tenantId column → system-global delete
+    ["sys~impl", { isImplicit: true, source: "sysThing", table: { isDeleted: {} } }],
+    // softDelete:false entity → skipped
+    [
+      "audit~impl",
+      { isImplicit: true, source: "auditEntry", table: { tenantId: {}, isDeleted: {} } },
+    ],
+    // explicit (non-implicit) projection → skipped
+    ["custom", { isImplicit: false, source: "thing", table: { isDeleted: {} } }],
+  ]);
+  const registry = {
+    getAllProjections: () => projections,
+    getEntity: (name: string) =>
+      ({
+        thing: { softDelete: true },
+        sysThing: { softDelete: true },
+        auditEntry: { softDelete: false },
+      })[name],
+  };
+  return {
+    db: fakeDb,
+    registry,
+    systemUser: { tenantId: "t1" },
+    ...(opts.graceDays !== undefined && {
+      configResolver: { get: async () => opts.graceDays },
+    }),
+  } as unknown as AppContext;
+}
+
+describe("softDeleteCleanupJob handler", () => {
+  test("hard-deletes only softDelete implicit projections, tenant-scoped where the table has tenantId", async () => {
+    const calls: DeleteCall[] = [];
+    await softDeleteCleanupJob({}, makeCtx({ calls }));
+
+    // thing + sysThing deleted; auditEntry (softDelete:false) + custom (explicit) skipped
+    expect(calls).toHaveLength(2);
+
+    const tenantScoped = calls.filter((c) => c.where["tenantId"] === "t1");
+    const systemScoped = calls.filter((c) => c.where["tenantId"] === undefined);
+    expect(tenantScoped).toHaveLength(1);
+    expect(systemScoped).toHaveLength(1);
+
+    for (const c of calls) {
+      expect(c.where["isDeleted"]).toBe(true);
+      expect(c.where["deletedAt"]).toBeDefined();
+    }
+  });
+
+  test("cutoff defaults to DEFAULT_GRACE_DAYS when no config resolver", async () => {
+    const calls: DeleteCall[] = [];
+    await softDeleteCleanupJob({}, makeCtx({ calls }));
+    const cutoff = (calls[0]?.where["deletedAt"] as { lt: Temporal.Instant }).lt;
+    const expected = Temporal.Now.instant().subtract({ hours: DEFAULT_GRACE_DAYS * 24 });
+    expect(Math.abs(cutoff.epochMilliseconds - expected.epochMilliseconds)).toBeLessThan(10_000);
+  });
+
+  test("honours a per-tenant grace-days value from the config resolver", async () => {
+    const calls: DeleteCall[] = [];
+    await softDeleteCleanupJob({}, makeCtx({ calls, graceDays: 7 }));
+    const cutoff = (calls[0]?.where["deletedAt"] as { lt: Temporal.Instant }).lt;
+    const expected = Temporal.Now.instant().subtract({ hours: 7 * 24 });
+    expect(Math.abs(cutoff.epochMilliseconds - expected.epochMilliseconds)).toBeLessThan(10_000);
+  });
+
+  test("throws when the job context is missing db/registry", async () => {
+    await expect(softDeleteCleanupJob({}, {} as AppContext)).rejects.toThrow(
+      /ctx.db \+ ctx.registry/,
+    );
+  });
+});

package/src/engine/entity-handlers.ts

@@ -85,6 +85,10 @@ const listSchema = z.object({
   sortDirection: z.enum(["asc", "desc"]).optional(),
   offset: z.number().int().nonnegative().optional(),
   totalCount: z.boolean().optional(),
+  // Trash query: include soft-deleted rows. Honoured only for softDelete
+  // entities; the dispatcher mirrors it onto ctx.includeDeleted. Tenant +
+  // ownership filters still apply.
+  includeDeleted: z.boolean().optional(),
   filter: z
     .object({
       field: z.string(),
@@ -219,6 +223,7 @@ export function defineEntityQueryHandler(
         const listPayload = query.payload as ListPayload; // @cast-boundary engine-payload
         const result = await executor.list(listPayload, query.user, ctx.db, {
           ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
+          ...(ctx.includeDeleted === true && { includeDeleted: true }),
         });
         if (!hasRefFields) return result;
         const enrichedRows = await enrichWithReferences(

package/src/engine/registry.ts

@@ -8,6 +8,12 @@ import { asEntityTableMeta } from "../db/query";
 import { buildEntityTable } from "../db/table-builder";
 import { buildMetricName, validateMetricName } from "../observability";
 import { type QnType, qualifyEntityName } from "./qualified-name";
+import {
+  buildSoftDeleteCleanupJob,
+  SOFT_DELETE_CLEANUP_JOB,
+  SOFT_DELETE_GRACE_DAYS_KEY,
+  softDeleteGraceDaysConfig,
+} from "./soft-delete-cleanup";
 import type {
   AuthClaimsHookDef,
   ClaimKeyDefinition,
@@ -1320,6 +1326,20 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     return false;
   })();
 
+  // Auto-wire the soft-delete cleanup cron + its grace-days config key when ANY
+  // entity opts into softDelete — the framework owns this machinery, no feature
+  // declares it (mirrors the auto restore-handler). Job-runner reads getAllJobs
+  // ungated; config-resolver reads getConfigKey → default. Reserved owner
+  // segment, guarded against a real-feature collision.
+  if ([...entityMap.values()].some((e) => e.softDelete)) {
+    if (!jobMap.has(SOFT_DELETE_CLEANUP_JOB)) {
+      jobMap.set(SOFT_DELETE_CLEANUP_JOB, buildSoftDeleteCleanupJob());
+    }
+    if (!configKeyMap.has(SOFT_DELETE_GRACE_DAYS_KEY)) {
+      configKeyMap.set(SOFT_DELETE_GRACE_DAYS_KEY, softDeleteGraceDaysConfig);
+    }
+  }
+
   return {
     features: featureMap,
 

package/src/engine/soft-delete-cleanup.ts

@@ -0,0 +1,84 @@
+// Auto-generated soft-delete maintenance. Hard-deletes entity rows that have
+// been soft-deleted longer than the per-tenant grace period. Injected into the
+// registry (the job + its config key) whenever ANY entity opts into softDelete
+// — see createRegistry. Runtime twin to the auto restore-handler: softDelete:
+// true buys an entity restore + trash (ctx.includeDeleted) + this cleanup, with
+// no feature to wire.
+//
+// Hard-deleting the projection row leaves the event stream intact (source of
+// truth) — a full projection rebuild would replay created+deleted and
+// resurrect the row as isDeleted=true. That's acceptable: cleanup bounds LIVE
+// table growth; irreversible event-log purging is data-retention's job
+// (pruneEvents), a separate, consumer-lag-guarded path.
+
+import { deleteMany, type WhereObject } from "../db/query";
+import { SYSTEM_USER_ID } from "./system-user";
+import type { ConfigKeyDefinition, JobDefinition, JobHandlerFn } from "./types/config";
+
+// qualifyEntityName convention (feature:type:kebab-name) with a reserved
+// "soft-delete" owner — no real feature owns these; the framework synthesizes
+// them. The job-runner keys cron scheduling off the name, the config-resolver
+// off the key.
+export const SOFT_DELETE_CLEANUP_JOB = "soft-delete:job:cleanup";
+export const SOFT_DELETE_GRACE_DAYS_KEY = "soft-delete:config:grace-days";
+export const DEFAULT_GRACE_DAYS = 30;
+
+export const softDeleteGraceDaysConfig: ConfigKeyDefinition = {
+  type: "number",
+  default: DEFAULT_GRACE_DAYS,
+  scope: "tenant",
+  access: { read: ["TenantAdmin", "SystemAdmin"], write: ["SystemAdmin"] },
+  bounds: { min: 0 },
+};
+
+export const softDeleteCleanupJob: JobHandlerFn = async (_payload, ctx) => {
+  const { db, registry } = ctx;
+  if (!db || !registry) {
+    throw new Error("soft-delete cleanup: ctx.db + ctx.registry required (JobContext incomplete)");
+  }
+  // perTenant fan-out → one run per active tenant, systemUser scoped to it.
+  // The job's db is the boot DbConnection (NOT tenant-scoped), so every delete
+  // is explicitly tenant-filtered below — otherwise a tenant with a short grace
+  // would purge another tenant's still-within-grace rows.
+  const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
+  if (tenantId === undefined) {
+    // skip: cron fired without a perTenant fan-out tenant — nothing scoped to purge
+    return;
+  }
+
+  const resolved = ctx.configResolver
+    ? await ctx.configResolver.get(
+        SOFT_DELETE_GRACE_DAYS_KEY,
+        softDeleteGraceDaysConfig,
+        tenantId,
+        SYSTEM_USER_ID,
+        db,
+      )
+    : undefined;
+  const graceDays = typeof resolved === "number" && resolved >= 0 ? resolved : DEFAULT_GRACE_DAYS;
+  const cutoff = Temporal.Now.instant().subtract({ hours: graceDays * 24 });
+
+  for (const proj of registry.getAllProjections().values()) {
+    if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table) continue;
+    const entity = registry.getEntity(proj.source);
+    if (!entity?.softDelete) continue;
+    const where: WhereObject = { isDeleted: true, deletedAt: { lt: cutoff } };
+    // @cast-boundary column-presence probe — identical access the executor's
+    // list() does on table["tenantId"] to decide tenant-scoping.
+    if ((proj.table as Record<string, unknown>)["tenantId"] !== undefined) {
+      where["tenantId"] = tenantId;
+    }
+    await deleteMany(db, proj.table, where);
+  }
+};
+
+export function buildSoftDeleteCleanupJob(): JobDefinition {
+  return {
+    name: SOFT_DELETE_CLEANUP_JOB,
+    handler: softDeleteCleanupJob,
+    trigger: { cron: "0 3 * * *" },
+    perTenant: true,
+    concurrency: "skip",
+    runIn: "worker",
+  };
+}

package/src/engine/types/handlers.ts

@@ -329,6 +329,12 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
   readonly triggeredBy?: { readonly id: string; readonly tenantId: TenantId } | null;
   readonly _userId?: string | undefined;
   readonly _handlerType?: string | undefined;
+  // Trash query opt-in (soft-delete). When true, the auto entity-list handler
+  // asks the executor to include soft-deleted rows; a custom query handler can
+  // read it to branch its own logic. Set by the dispatcher from the query
+  // payload's `includeDeleted` field — visibility (tenant/ownership) filters
+  // still apply, so this never widens what a user may see beyond the live list.
+  readonly includeDeleted?: boolean;
 
   readonly query: (qn: string, payload: unknown) => Promise<unknown>;
   readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;

package/src/migrations/__tests__/pending-rebuilds.integration.test.ts

@@ -200,6 +200,19 @@ describe("pending-rebuilds queue", () => {
     expect(run).toEqual({ rebuilt: [], failed: [], unmapped: [], unresolvedManaged: [] });
   });
 
+  // Zwei applied-Migrations, die dieselbe Tabelle anfassen, dürfen sie nur
+  // EINMAL queuen (interner Set) — sonst rebuildet ein Run dieselbe Projektion
+  // doppelt.
+  test("two applied migrations touching the same table → deduplicated to one entry", async () => {
+    writeRebuildMarker(markerDir, "0006_a.sql", ["read_pending_counts"]);
+    writeRebuildMarker(markerDir, "0006_b.sql", ["read_pending_counts"]);
+    const queued = await queueRebuildsFromMarkers(testDb.db, {
+      migrationsDir: markerDir,
+      appliedIds: ["0006_a", "0006_b"],
+    });
+    expect(queued).toEqual(["read_pending_counts"]);
+  });
+
   // #361: eine managed-Tabelle (Marker tragen nur managed), die in DIESEM Run
   // geleert wurde, aber keine Projektion auflöst = owning-Feature fehlt in der
   // Komposition → laut (unresolvedManaged), aber non-fatal (gedraint, kein Throw).

package/src/pipeline/dispatcher.ts

@@ -247,6 +247,7 @@ export function createDispatcher(
     user: SessionUser,
     tx?: DbTx,
     afterCommitHooks?: AfterCommitHook[],
+    includeDeleted?: boolean,
   ): HandlerContext {
     const isSystem = registry.isHandlerSystemScoped(type);
     // The outer dispatcher receives a DbConnection from the server/stack;
@@ -573,6 +574,7 @@ export function createDispatcher(
       _userId: user.id,
       _tenantId: user.tenantId,
       _handlerType: type,
+      ...(includeDeleted && { includeDeleted: true }),
       ...bridge,
     } as HandlerContext; // @cast-boundary engine-bridge
   }
@@ -773,7 +775,15 @@ export function createDispatcher(
       throw validationErrorFromZod(parsed.error);
     }
 
-    const handlerContext = buildHandlerContext(type, user, tx);
+    // Trash opt-in rides the validated query payload: only the entity-list
+    // schema (and custom query schemas that opt in) carries `includeDeleted`,
+    // so other handlers never see the flag. Visibility filters still apply
+    // downstream (see HandlerContext.includeDeleted) — safe from raw input.
+    const includeDeleted =
+      typeof parsed.data === "object" &&
+      parsed.data !== null &&
+      (parsed.data as Record<string, unknown>)["includeDeleted"] === true; // @cast-boundary validated-payload
+    const handlerContext = buildHandlerContext(type, user, tx, undefined, includeDeleted);
     let result = await handler.handler({ type, payload: parsed.data, user }, handlerContext);
 
     // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data