@cosmicdrift/kumiko-framework 0.2.2 → 0.3.0

package/src/files/zip-stream.ts

@@ -0,0 +1,251 @@
+import { getTemporal } from "../time";
+
+// Streaming-ZIP-Builder (S2.U3 Atom 3a) — pure-JS, dependency-frei.
+//
+// **Format-Wahl: STORE (kein DEFLATE).** Compression-frei + minimal —
+// fuer User-Data-Export-Bundles akzeptabel weil:
+//   - Storage-Provider (S3/R2) komprimiert eh on-the-wire (HTTP gzip)
+//   - JSON-Snippets sind klein, File-Binaries sind oft schon komprimiert
+//     (PNG/JPG/PDF/MP4/...)
+//   - DEFLATE braucht zlib + buffering pro Entry, killt das Streaming-
+//     Property
+//
+// **Streaming-Property:** Caller gibt `AsyncIterable<ZipEntry>`, jeder
+// Entry hat `data: AsyncIterable<Uint8Array>`. ZIP-Bytes werden
+// chunk-fuer-chunk yieldet — kein Entry haengt im Memory bis er fertig
+// ist. Storage-Provider's writeStream konsumiert direkt durch.
+//
+// **ZIP-Standard:** APPNOTE.TXT v6.3.10 (April 2022). STORE-Method,
+// kein ZIP64 (max 4 GB pro Entry, max 65535 Entries — fuer User-Daten-
+// Exports ausreichend; ZIP64-Support kommt wenn ein realer User mit
+// >4 GB single-File auftaucht). Kein UTF-8-Flag (filenames sind ASCII
+// in unserem Use-Case: "profile.json", "files/<id>.<ext>").
+//
+// **CRC32:** klassisches IEEE-802.3-Polynom (0xEDB88320). Lookup-Table
+// einmal initialisiert + cached.
+
+const ZIP_VERSION_NEEDED = 20; // 2.0 = STORE
+const ZIP_METHOD_STORE = 0;
+
+// Local file header signature: 0x04034b50 = "PK\x03\x04"
+const LOCAL_FILE_HEADER_SIG = 0x04034b50;
+// Central directory file header signature: 0x02014b50 = "PK\x01\x02"
+const CENTRAL_DIR_HEADER_SIG = 0x02014b50;
+// End of central directory record signature: 0x06054b50 = "PK\x05\x06"
+const EOCD_SIG = 0x06054b50;
+
+const VERSION_MADE_BY = 0x031e; // 0x03 = UNIX, 0x1e = ZIP 3.0
+
+// General Purpose Flag Bit 11 (0x0800) = UTF-8 filename + comment encoding.
+// Wird default-on gesetzt: ASCII ist gueltiges UTF-8, also Win-Win.
+// Ohne Flag interpretieren aeltere ZIP-Tools filenames als CP437 — bei
+// Umlauten ("Bügel.pdf") wird das Mojibake.
+const GENERAL_PURPOSE_FLAGS = 0x0800;
+
+// External-Attrs (UNIX-Mode in High-Bytes) fuer regulaere Dateien mit
+// 0644-Permissions: `(S_IFREG | 0644) << 16 = 0o100644 << 16 = 0x81a40000`.
+// S_IFREG = 0o100000 (regular file), 0o644 = rw-r--r--. Ohne diese
+// Bits entpackt Info-ZIP mit Mode 0000 (EACCES beim Read).
+const UNIX_REGULAR_FILE_0644 = 0o100644 << 16; // 0x81a40000
+
+// ZIP-Format-Limits ohne ZIP64-Extension. Atom 3a-Scope ist STORE-only;
+// ZIP64 kommt wenn ein realer User-Export diese Caps reisst.
+const ZIP_MAX_ENTRY_SIZE = 0xffffffff; // uint32 → 4 GB
+const ZIP_MAX_ENTRIES = 0xffff; // uint16 → 65535
+
+export interface ZipEntry {
+  /** Pfad im ZIP, slash-separated. ASCII (kein UTF-8-Flag gesetzt). */
+  readonly path: string;
+  /** Body als AsyncIterable — kann lazy generated sein (kein Upfront-Memory). */
+  readonly data: AsyncIterable<Uint8Array>;
+  /**
+   * Optional Modification-Time. Default = Now. ZIP nutzt MS-DOS-Format
+   * (2-Sek-Aufloesung). Wer Audit-Trail-Zeitpunkte haben will, setzt
+   * den Generation-Timestamp ueber alle Entries.
+   */
+  readonly mtime?: InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
+}
+
+/**
+ * Erzeugt einen ZIP-Stream als `AsyncIterable<Uint8Array>`. Caller (z.B.
+ * `FileStorageProvider.writeStream`) konsumiert chunk-fuer-chunk, kein
+ * Entry haengt im Memory bis fertig.
+ *
+ * Streaming-Lifecycle pro Entry:
+ *   1. Local File Header (mit CRC32+size=0 als Placeholder; wir nutzen
+ *      KEINE Streaming-Data-Descriptor weil Storage-Provider Random-
+ *      Access nicht garantiert — wir collecten den Body in Memory pro
+ *      Entry um CRC + size **vor** dem Header zu kennen.
+ *      Trade-off: 1 Entry-Body im Memory at-a-time; bei <100 MB Files
+ *      OK, bei >1 GB single-Files braeuchte ZIP64+Streaming-Descriptor).
+ *   2. File Body (raw bytes)
+ * Am Ende:
+ *   3. Central Directory (eine Liste-Entry pro File mit CRC + size)
+ *   4. EOCD (End Of Central Directory)
+ */
+export async function* createZipStream(
+  entries: AsyncIterable<ZipEntry>,
+): AsyncIterable<Uint8Array> {
+  const centralDirRecords: Uint8Array[] = [];
+  let offset = 0; // Bytes-Counter fuer central-dir entry's local-header-offset
+
+  for await (const entry of entries) {
+    // Body in Memory collecten — wir brauchen CRC32 + size VOR dem
+    // local-file-header (kein streaming-data-descriptor weil
+    // file-storage-providers nicht zwingend seek-able sind, aber wir
+    // wollen vermeiden dass der konsumierende Storage zwei-pass laesst).
+    const body = await collectBody(entry.data);
+
+    // Hard-Limit: STORE-Mode ohne ZIP64-Extension cappt bei uint32 (4 GB).
+    // Bei Ueberschreitung wuerde der Integer-Wrap silent ein korruptes
+    // ZIP produzieren (Decoder lesen Muell-Sizes). Lieber early-fail mit
+    // klarer Begruendung — Worker (Atom 3b) fängt das + setzt Job=failed.
+    if (body.byteLength > ZIP_MAX_ENTRY_SIZE) {
+      throw new Error(
+        `ZIP-Entry "${entry.path}" exceeds 4 GB limit (${body.byteLength} bytes). ` +
+          `STORE-mode without ZIP64-extension caps at uint32. ` +
+          `Add ZIP64-support before exporting >4 GB single-files.`,
+      );
+    }
+    if (centralDirRecords.length >= ZIP_MAX_ENTRIES) {
+      throw new Error(
+        `ZIP archive exceeds ${ZIP_MAX_ENTRIES}-entry limit. ` +
+          `Add ZIP64-support before exporting >${ZIP_MAX_ENTRIES} entries.`,
+      );
+    }
+
+    const crc = crc32(body);
+    const size = body.byteLength;
+    const filenameBytes = new TextEncoder().encode(entry.path);
+    const dosTime = toDosTime(entry.mtime ?? getTemporal().Now.instant());
+
+    // Local File Header
+    const lfh = new Uint8Array(30 + filenameBytes.byteLength);
+    const lfhView = new DataView(lfh.buffer);
+    lfhView.setUint32(0, LOCAL_FILE_HEADER_SIG, true);
+    lfhView.setUint16(4, ZIP_VERSION_NEEDED, true);
+    lfhView.setUint16(6, GENERAL_PURPOSE_FLAGS, true);
+    lfhView.setUint16(8, ZIP_METHOD_STORE, true);
+    lfhView.setUint16(10, dosTime.time, true);
+    lfhView.setUint16(12, dosTime.date, true);
+    lfhView.setUint32(14, crc, true);
+    lfhView.setUint32(18, size, true); // compressed size = uncompressed (STORE)
+    lfhView.setUint32(22, size, true);
+    lfhView.setUint16(26, filenameBytes.byteLength, true);
+    lfhView.setUint16(28, 0, true); // extra field length
+    lfh.set(filenameBytes, 30);
+
+    yield lfh;
+    yield body;
+
+    // Central-Directory-Eintrag fuer diesen Entry — wir collecten ihn,
+    // emittieren ihn am Ende.
+    const cdh = new Uint8Array(46 + filenameBytes.byteLength);
+    const cdhView = new DataView(cdh.buffer);
+    cdhView.setUint32(0, CENTRAL_DIR_HEADER_SIG, true);
+    cdhView.setUint16(4, VERSION_MADE_BY, true);
+    cdhView.setUint16(6, ZIP_VERSION_NEEDED, true);
+    cdhView.setUint16(8, GENERAL_PURPOSE_FLAGS, true);
+    cdhView.setUint16(10, ZIP_METHOD_STORE, true);
+    cdhView.setUint16(12, dosTime.time, true);
+    cdhView.setUint16(14, dosTime.date, true);
+    cdhView.setUint32(16, crc, true);
+    cdhView.setUint32(20, size, true);
+    cdhView.setUint32(24, size, true);
+    cdhView.setUint16(28, filenameBytes.byteLength, true);
+    cdhView.setUint16(30, 0, true); // extra field length
+    cdhView.setUint16(32, 0, true); // comment length
+    cdhView.setUint16(34, 0, true); // disk number start
+    cdhView.setUint16(36, 0, true); // internal file attrs
+    cdhView.setUint32(38, UNIX_REGULAR_FILE_0644, true);
+    cdhView.setUint32(42, offset, true); // local-header-offset
+    cdh.set(filenameBytes, 46);
+    centralDirRecords.push(cdh);
+
+    offset += lfh.byteLength + body.byteLength;
+  }
+
+  // Central Directory: alle entries hintereinander
+  const centralDirStart = offset;
+  let centralDirSize = 0;
+  for (const record of centralDirRecords) {
+    yield record;
+    centralDirSize += record.byteLength;
+  }
+
+  // EOCD (End Of Central Directory)
+  const eocd = new Uint8Array(22);
+  const eocdView = new DataView(eocd.buffer);
+  eocdView.setUint32(0, EOCD_SIG, true);
+  eocdView.setUint16(4, 0, true); // disk number
+  eocdView.setUint16(6, 0, true); // disk where central-dir starts
+  eocdView.setUint16(8, centralDirRecords.length, true); // entries on this disk
+  eocdView.setUint16(10, centralDirRecords.length, true); // total entries
+  eocdView.setUint32(12, centralDirSize, true);
+  eocdView.setUint32(16, centralDirStart, true);
+  eocdView.setUint16(20, 0, true); // .zip comment length
+  yield eocd;
+}
+
+async function collectBody(source: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for await (const chunk of source) {
+    chunks.push(chunk);
+    total += chunk.byteLength;
+  }
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const c of chunks) {
+    out.set(c, off);
+    off += c.byteLength;
+  }
+  return out;
+}
+
+// CRC32 — IEEE-802.3-Polynom (0xEDB88320, reversed). Lookup-Table einmal.
+let CRC32_TABLE: Uint32Array | null = null;
+function buildCrcTable(): Uint32Array {
+  const table = new Uint32Array(256);
+  for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let k = 0; k < 8; k++) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[i] = c >>> 0;
+  }
+  return table;
+}
+
+function crc32(data: Uint8Array): number {
+  if (!CRC32_TABLE) CRC32_TABLE = buildCrcTable();
+  let crc = 0xffffffff;
+  for (let i = 0; i < data.byteLength; i++) {
+    const byte = data[i] ?? 0;
+    const idx = (crc ^ byte) & 0xff;
+    crc = ((CRC32_TABLE[idx] ?? 0) ^ (crc >>> 8)) >>> 0;
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+// MS-DOS Date+Time encoding fuer ZIP-Header.
+// Date: bits 9-15=year-1980, 5-8=month, 0-4=day.
+// Time: bits 11-15=hour, 5-10=minute, 0-4=second/2.
+//
+// **UTC** statt lokaler Zeitzone: in einem DSGVO-Kontext ist der
+// ZIP-mtime Teil des Auskunfts-Artefakts. Verschiedene Server-Zeitzonen
+// wuerden sonst verschiedene mtime-Werte fuer denselben Generation-
+// Instant produzieren — Audit-Drift. UTC ist der Standard fuer alle
+// server-side-Timestamps im Repo (Temporal.Instant ueberall).
+function toDosTime(i: InstanceType<ReturnType<typeof getTemporal>["Instant"]>): {
+  date: number;
+  time: number;
+} {
+  const dt = i.toZonedDateTimeISO("UTC");
+  const year = dt.year;
+  const date =
+    (((Math.max(year - 1980, 0) & 0x7f) << 9) | ((dt.month & 0x0f) << 5) | (dt.day & 0x1f)) >>> 0;
+  const time =
+    (((dt.hour & 0x1f) << 11) | ((dt.minute & 0x3f) << 5) | ((dt.second >> 1) & 0x1f)) >>> 0;
+  return { date, time };
+}

package/src/jobs/job-runner.ts

@@ -104,7 +104,7 @@ const TRACE_CONTEXT_KEY = "_traceContext";
 function readTraceContext(data: Record<string, unknown>): SerializedTraceContext | undefined {
   const raw = data[TRACE_CONTEXT_KEY];
   if (!raw || typeof raw !== "object") return undefined;
-  const ctx = raw as Partial<SerializedTraceContext>;
+  const ctx = raw as Partial<SerializedTraceContext>; // @cast-boundary engine-payload
   if (!ctx.traceId || !ctx.spanId) return undefined;
   return { traceId: ctx.traceId, spanId: ctx.spanId };
 }
@@ -198,7 +198,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     for (const list of results) {
       for (const j of list) {
         if (j.name !== jobName) continue;
-        const t = (j.data as { _tenantId?: string } | undefined)?._tenantId;
+        const t = (j.data as { _tenantId?: string } | undefined)?._tenantId; // @cast-boundary dynamic-key
         if (t === tenantId) {
           count += 1;
           if (count >= max) return true;
@@ -274,8 +274,8 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     // without peeking at BullMQ internals.
     const rawData = bullJob.data as DbRow;
     const meta: JobMeta = {
-      triggeredById: rawData["_triggeredById"] as string | undefined,
-      payload: rawData["_payload"] as string | undefined,
+      triggeredById: rawData["_triggeredById"] as string | undefined, // @cast-boundary dynamic-key
+      payload: rawData["_payload"] as string | undefined, // @cast-boundary dynamic-key
       attempt: bullJob.attemptsMade + 1,
     };
 
@@ -287,16 +287,16 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
 
     // Determine tenantId and triggeredBy from meta
     const tenantId =
-      (rawData["_tenantId"] as string | undefined) ??
-      (payload["tenantId"] as string | undefined) ??
+      (rawData["_tenantId"] as string | undefined) ?? // @cast-boundary dynamic-key
+      (payload["tenantId"] as string | undefined) ?? // @cast-boundary dynamic-key
       SYSTEM_TENANT_ID;
-    const triggeredById = (rawData["_triggeredById"] as string | undefined) ?? null;
+    const triggeredById = (rawData["_triggeredById"] as string | undefined) ?? null; // @cast-boundary dynamic-key
 
     // _triggerName aus rawData übernehmen falls gesetzt — handleEvent
     // packt das beim Multi-Trigger-Dispatch rein (siehe unten). Über
     // jobContext.triggerName freigegeben damit der Handler nicht selbst
     // im rohen Payload kramen muss.
-    const triggerName = rawData["_triggerName"] as string | undefined;
+    const triggerName = rawData["_triggerName"] as string | undefined; // @cast-boundary dynamic-key
     const jobContext: AppContext = {
       ...context,
       systemUser: createSystemUser(tenantId),
@@ -317,7 +317,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     // so event writes during this job stamp the same correlation as the
     // request that scheduled it. Cron/boot jobs (no scheduler) start fresh
     // — correlationId = new requestId, no parent causation.
-    const inheritedCorrelationId = (rawData["_correlationId"] as string | undefined) ?? undefined;
+    const inheritedCorrelationId = (rawData["_correlationId"] as string | undefined) ?? undefined; // @cast-boundary dynamic-key
     const jobRequestId = requestContext.generateId();
     const jobCorrelationId = inheritedCorrelationId ?? jobRequestId;
 
@@ -460,7 +460,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       // dispatch). Fan-out children of perTenant jobs land here on their
       // recursive queue.add and DO carry _tenantId.
       if (jobDef.maxPerTenant !== undefined) {
-        const tenantId = (payload as { _tenantId?: string } | undefined)?._tenantId;
+        const tenantId = (payload as { _tenantId?: string } | undefined)?._tenantId; // @cast-boundary dynamic-key
         if (
           tenantId !== undefined &&
           (await isOverPerTenantLimit(jobName, tenantId, jobDef.maxPerTenant))

package/src/lifecycle/lifecycle.ts

@@ -146,9 +146,6 @@ export function createLifecycle(opts: LifecycleOptions = {}): Lifecycle {
   };
 }
 
-// Builds a single error-log closure once per lifecycle instance. Structured
-// logger wins when present; otherwise plain stderr via console.error so we
-// never eat a failure silently.
 function makeErrorLogger(
   logger: Pick<Logger, "error"> | undefined,
 ): (msg: string, err: unknown) => void {

package/src/logging/index.ts

@@ -1,3 +1,4 @@
 export type { LoggerOptions } from "./pino-logger";
 export { createLogger } from "./pino-logger";
 export type { Logger } from "./types";
+export { createFallbackLogger } from "./utils";

package/src/logging/pino-logger.ts

@@ -11,7 +11,7 @@ export type LoggerOptions = {
 };
 
 export function createLogger(options: LoggerOptions = {}): Logger {
-  const level = options.level ?? (process.env["LOG_LEVEL"] as LoggerOptions["level"]) ?? "info";
+  const level = options.level ?? (process.env["LOG_LEVEL"] as LoggerOptions["level"]) ?? "info"; // @cast-boundary dynamic-key
   const pretty = options.pretty ?? process.env["LOG_FORMAT"] === "pretty";
 
   const pinoConfig = {
@@ -43,22 +43,26 @@ function wrapPino(p: pino.Logger): Logger {
   return {
     info(msg, data) {
       const merged = mergeTraceFields(data);
-      merged ? p.info(merged, msg) : p.info(msg);
+      if (merged) p.info(merged, msg);
+      else p.info(msg);
     },
     warn(msg, data) {
       const merged = mergeTraceFields(data);
-      merged ? p.warn(merged, msg) : p.warn(msg);
+      if (merged) p.warn(merged, msg);
+      else p.warn(msg);
     },
     error(msg, data) {
       const merged = mergeTraceFields(data);
-      merged ? p.error(merged, msg) : p.error(msg);
+      if (merged) p.error(merged, msg);
+      else p.error(msg);
     },
     debug(msg, data) {
       const merged = mergeTraceFields(data);
-      merged ? p.debug(merged, msg) : p.debug(msg);
+      if (merged) p.debug(merged, msg);
+      else p.debug(msg);
     },
-    child(context) {
-      return wrapPino(p.child(context));
+    child(ctx) {
+      return wrapPino(p.child(ctx));
     },
   };
 }

package/src/logging/utils.ts

@@ -0,0 +1,24 @@
+import type { Logger } from "./types";
+
+type FallbackLogger = {
+  error(msg: string, data?: Record<string, unknown>): void;
+};
+
+export function createFallbackLogger(
+  namespace: string,
+  logger?: Pick<Logger, "error"> | undefined,
+): FallbackLogger {
+  if (logger) {
+    return {
+      error(msg, data) {
+        logger.error(`[${namespace}] ${msg}`, data);
+      },
+    };
+  }
+  return {
+    error(msg, data) {
+      // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
+      console.error(`[${namespace}] ${msg}:`, data);
+    },
+  };
+}

package/src/observability/prometheus-meter.ts

@@ -244,21 +244,23 @@ export function serializeOpenMetrics(meter: PrometheusMeter): string {
   for (const name of names) {
     const entry = snap.get(name);
     if (!entry) continue;
-    const { def, slots } = entry;
+    const { def } = entry;
     if (def.description) lines.push(`# HELP ${name} ${def.description}`);
     lines.push(`# TYPE ${name} ${def.type}`);
 
-    // @cast-boundary engine-bridge — slots union narrows by def.type
     if (def.type === "counter") {
-      for (const s of slots as CounterState[]) {
+      const counterSlots = entry.slots as CounterState[]; // @cast-boundary engine-bridge
+      for (const s of counterSlots) {
         lines.push(`${name}${renderLabels(s.labels)} ${s.value}`);
       }
     } else if (def.type === "gauge") {
-      for (const s of slots as GaugeState[]) {
+      const gaugeSlots = entry.slots as GaugeState[]; // @cast-boundary engine-bridge
+      for (const s of gaugeSlots) {
         lines.push(`${name}${renderLabels(s.labels)} ${s.value}`);
       }
     } else {
-      for (const s of slots as HistogramState[]) {
+      const histSlots = entry.slots as HistogramState[]; // @cast-boundary engine-bridge
+      for (const s of histSlots) {
         // Cumulative bucket counts + +Inf terminator + sum/count suffixes.
         let cumulative = 0;
         for (let i = 0; i < s.boundaries.length; i++) {

package/src/pipeline/__tests__/archive-stream.integration.ts

@@ -49,7 +49,7 @@ const archFeature = defineFeature("archtest", (r) => {
     "item:relabel",
     z.object({ id: z.uuid(), label: z.string() }),
     async (event, ctx) => {
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: event.payload.id,
         aggregateType: "arch-item",
         type: labelChanged.name,

package/src/pipeline/__tests__/causation-chain.integration.ts

@@ -65,7 +65,7 @@ const causationFeature = defineFeature("causation", (r) => {
     async (event, ctx) => {
       const created = await orderExecutor.create({ item: event.payload.item }, event.user, ctx.db);
       if (!created.isSuccess) return created;
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: String(created.data.id),
         aggregateType: "causation-order",
         type: placed.name,

package/src/pipeline/__tests__/domain-events-projections.integration.ts

@@ -105,7 +105,7 @@ const shippingFeature = defineFeature("shipping", (r) => {
     "shipment:bill",
     z.object({ id: z.uuid(), cost: z.number() }),
     async (event, ctx) => {
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: event.payload.id,
         aggregateType: "domain-shipment",
         type: shipmentBilled.name,
@@ -137,7 +137,7 @@ const shippingFeature = defineFeature("shipping", (r) => {
     "shipment:bill-unregistered",
     z.object({ id: z.uuid() }),
     async (event, ctx) => {
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: event.payload.id,
         aggregateType: "domain-shipment",
         type: "shipping:event:ghost", // never defined via r.defineEvent
@@ -152,7 +152,7 @@ const shippingFeature = defineFeature("shipping", (r) => {
     "shipment:bill-bad-payload",
     z.object({ id: z.uuid() }),
     async (event, ctx) => {
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: event.payload.id,
         aggregateType: "domain-shipment",
         type: shipmentBilled.name,

package/src/pipeline/__tests__/event-define-event-strict.integration.ts

@@ -49,7 +49,7 @@ const emitterFeature = defineFeature("emitter", (r) => {
     "emit:valid",
     z.object({ userId: z.uuid(), email: z.email() }),
     async (cmd, ctx) => {
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: cmd.payload.userId,
         aggregateType: "user",
         type: welcome.name,
@@ -66,7 +66,7 @@ const emitterFeature = defineFeature("emitter", (r) => {
     async (cmd, ctx) => {
       // Deliberately NOT passing welcome.name — "emitter:event:not-registered"
       // was never registered. ctx.appendEvent must reject at the append site.
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: cmd.payload.userId,
         aggregateType: "user",
         type: "emitter:event:not-registered",
@@ -82,7 +82,7 @@ const emitterFeature = defineFeature("emitter", (r) => {
     z.object({ userId: z.uuid() }),
     async (cmd, ctx) => {
       // userId is correct but email is missing / not an email string.
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: cmd.payload.userId,
         aggregateType: "user",
         type: welcome.name,
@@ -100,7 +100,7 @@ const emitterFeature = defineFeature("emitter", (r) => {
       // "neighbor:event:neighbor-signal" is owned by the neighbor feature.
       // The ownership guard in appendDomainEventCore must reject this append
       // at emit-site — cross-feature emission silently breaks encapsulation.
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: cmd.payload.userId,
         aggregateType: "user",
         type: foreignEventName,

package/src/pipeline/__tests__/load-aggregate-query.integration.ts

@@ -66,7 +66,7 @@ const asOfFeature = defineFeature("asoftest", (r) => {
     "invoice:approve",
     z.object({ id: z.uuid(), amount: z.number().int(), approvedBy: z.string() }),
     async (event, ctx) => {
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: event.payload.id,
         aggregateType: "asof-invoice",
         type: approved.name,

package/src/pipeline/__tests__/msp-multi-hop.integration.ts

@@ -55,7 +55,7 @@ const mmhFeature = defineFeature("mmh", (r) => {
     async (event, ctx) => {
       const created = await orderExecutor.create({ item: event.payload.item }, event.user, ctx.db);
       if (!created.isSuccess) return created;
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: String(created.data.id),
         aggregateType: "mmh-order",
         type: placed.name,
@@ -75,7 +75,7 @@ const mmhFeature = defineFeature("mmh", (r) => {
         if (!ctx) throw new Error("MSP-apply ctx missing — regression of C.2b wiring");
         const history = await ctx.loadAggregate(event.aggregateId);
         confirmLoadCounts.push(history.length);
-        await ctx.appendEventUnsafe({
+        await ctx.unsafeAppendEvent({
           aggregateId: event.aggregateId,
           aggregateType: "mmh-order",
           type: confirmed.name,
@@ -91,7 +91,7 @@ const mmhFeature = defineFeature("mmh", (r) => {
     apply: {
       [confirmed.name]: async (event, _tx, ctx) => {
         if (!ctx) throw new Error("MSP-apply ctx missing — regression of C.2b wiring");
-        await ctx.appendEventUnsafe({
+        await ctx.unsafeAppendEvent({
           aggregateId: event.aggregateId,
           aggregateType: "mmh-order",
           type: shipped.name,

package/src/pipeline/__tests__/msp-rebuild.integration.ts

@@ -139,7 +139,7 @@ const feature = defineFeature("mspreb", (r) => {
     apply: {
       [invoiceBilled.name]: async (event, _tx, ctx) => {
         const p = event.payload as { customer: string };
-        await ctx.appendEventUnsafe({
+        await ctx.unsafeAppendEvent({
           aggregateId: p.customer,
           aggregateType: "msp-reb-invoice",
           type: escalationTriggered.name,
@@ -166,7 +166,7 @@ const feature = defineFeature("mspreb", (r) => {
         ctx.db,
       );
       if (!res.isSuccess) return res;
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: String(res.data.id),
         aggregateType: "msp-reb-invoice",
         type: invoiceBilled.name,
@@ -187,7 +187,7 @@ const feature = defineFeature("mspreb", (r) => {
         ctx.db,
       );
       if (!res.isSuccess) return res;
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: String(res.data.id),
         aggregateType: "msp-reb-payment",
         type: paymentReceived.name,

package/src/pipeline/__tests__/multi-stream-projection.integration.ts

@@ -124,7 +124,7 @@ const mspFeature = defineFeature("msptest", (r) => {
         ctx.db,
       );
       if (!res.isSuccess) return res;
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: String(res.data.id),
         aggregateType: "msp-shipment",
         type: shipmentBilled.name,
@@ -145,7 +145,7 @@ const mspFeature = defineFeature("msptest", (r) => {
         ctx.db,
       );
       if (!res.isSuccess) return res;
-      await ctx.appendEventUnsafe({
+      await ctx.unsafeAppendEvent({
         aggregateId: String(res.data.id),
         aggregateType: "msp-refund",
         type: refundIssued.name,

package/src/pipeline/__tests__/query-projection.integration.ts

@@ -96,10 +96,10 @@ const qpFeature = defineFeature("qp", (r) => {
 
   r.queryHandler(
     "widget:list-system",
-    z.object({ allTenants: z.boolean().optional() }),
+    z.object({ unsafeAllTenants: z.boolean().optional() }),
     async (query, ctx) =>
       ctx.queryProjection("qp:projection:widget-audit", {
-        allTenants: query.payload.allTenants ?? false,
+        unsafeAllTenants: query.payload.unsafeAllTenants ?? false,
       }),
     { access: { openToAll: true } },
   );
@@ -172,8 +172,8 @@ describe("ctx.queryProjection", () => {
     expect(rows.map((r) => r.label).sort()).toEqual(["X", "Y"]);
   });
 
-  test("allTenants=true bypasses tenant filter on tenant-scoped projection", async () => {
-    // Repurpose list-system by passing allTenants=true — but list-system is
+  test("unsafeAllTenants=true bypasses tenant filter on tenant-scoped projection", async () => {
+    // Repurpose list-system by passing unsafeAllTenants=true — but list-system is
     // already no-tenant-column. The semantic matters when a projection HAS
     // tenant_id but the handler wants a cross-tenant sweep (audit). We
     // exercise that contract via a direct queryProjection call here.
@@ -186,7 +186,7 @@ describe("ctx.queryProjection", () => {
     //  surface small — assert against the two query handlers we have.)
     const sys = await stack.http.queryOk<Array<{ label: string }>>(
       "qp:query:widget:list-system",
-      { allTenants: true },
+      { unsafeAllTenants: true },
       admin,
     );
     expect(sys).toHaveLength(2);