@cosmicdrift/kumiko-framework 0.2.3 → 0.4.0

package/src/event-store/upcaster-dead-letter.ts

@@ -115,5 +115,5 @@ export async function listDeadLetters(
           .from(upcasterDeadLetterTable)
           .orderBy(desc(upcasterDeadLetterTable.createdAt))
           .limit(limit);
-  return rows as readonly DeadLetterRow[];
+  return rows as readonly DeadLetterRow[]; // @cast-boundary db-row
 }

package/src/event-store/upcaster.ts

@@ -88,7 +88,7 @@ async function upcastStoredEventWithPolicy(
   if (!info) return event;
   if (event.eventVersion >= info.currentVersion) return event;
 
-  let payload = event.payload as unknown;
+  let payload = event.payload as unknown; // @cast-boundary engine-payload
   let v = event.eventVersion;
   const startVersion = event.eventVersion;
   while (v < info.currentVersion) {

package/src/files/file-routes.ts

@@ -346,7 +346,7 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
       .select()
       .from(fileRefsTable)
       .where(and(eq(fileRefsTable.id, id), eq(fileRefsTable.tenantId, tenantId)));
-    return (row as FileRef | undefined) ?? null;
+    return (row as FileRef | undefined) ?? null; // @cast-boundary db-row
   }
 
   return api;

package/src/files/types.ts

@@ -1,4 +1,4 @@
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { TenantId } from "../engine/types/identifiers";
 
 export type FileMetadata = {
   readonly fileName: string;
@@ -99,7 +99,7 @@ const EXTENSION_MIME_WHITELIST: Record<string, readonly string[]> = {
   csv: ["text/csv", "application/csv", "text/plain"],
   json: ["application/json", "text/json"],
   md: ["text/markdown", "text/plain"],
-};
+} satisfies Record<string, readonly string[]>;
 
 export function validateFile(
   metadata: FileMetadata,

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);

package/src/pipeline/append-event-core.ts

@@ -41,12 +41,21 @@ function eventOwnerFeature(qualifiedName: string): string | undefined {
   return idx > 0 ? qualifiedName.slice(0, idx) : undefined;
 }
 
+// System-event prefix: events under this namespace bypass the registry +
+// ownership checks. Reserved for framework-internal coordination (step-
+// engine deferred dispatch, lifecycle signals). The matching MSP filters
+// on the literal type-string. Apps cannot write into "kumiko:system:*"
+// directly — only framework step implementations call unsafeAppendEvent
+// with these types.
+const SYSTEM_EVENT_PREFIX = "kumiko:system:";
+
 export async function appendDomainEventCore(
   deps: AppendDomainEventCoreDeps,
   args: AppendEventArgs,
 ): Promise<StoredEvent> {
+  const isSystemEvent = args.type.startsWith(SYSTEM_EVENT_PREFIX);
   const eventDef = deps.registry.getEvent(args.type);
-  if (!eventDef) {
+  if (!eventDef && !isSystemEvent) {
     throw new InternalError({
       message: `${deps.callSiteLabel}("${args.type}") — event not registered. Call r.defineEvent(shortName, schema) in a feature; appendEvent expects the qualified name returned by defineEvent (e.g. "<feature>:event:<short>").`,
     });
@@ -61,7 +70,7 @@ export async function appendDomainEventCore(
   // Feature names are registered case-preserving (pubsubOrders) but qualified
   // into kebab-case for the event/handler names (pubsub-orders:event:…) — so
   // we compare the kebab form on both sides.
-  if (deps.callerFeature) {
+  if (deps.callerFeature && !isSystemEvent) {
     const owner = eventOwnerFeature(args.type);
     const callerKebab = toKebab(deps.callerFeature);
     if (owner && owner !== callerKebab) {
@@ -70,9 +79,16 @@ export async function appendDomainEventCore(
       });
     }
   }
-  const parsed = eventDef.schema.safeParse(args.payload ?? {});
-  if (!parsed.success) throw validationErrorFromZod(parsed.error);
-  const validatedPayload = parsed.data as Record<string, unknown>; // @cast-boundary engine-payload
+  // System events skip schema validation — payload shape is owned by the
+  // framework step that emits + the bundled MSP that consumes.
+  let validatedPayload: Record<string, unknown>;
+  if (eventDef) {
+    const parsed = eventDef.schema.safeParse(args.payload ?? {});
+    if (!parsed.success) throw validationErrorFromZod(parsed.error);
+    validatedPayload = parsed.data as Record<string, unknown>;
+  } else {
+    validatedPayload = (args.payload ?? {}) as Record<string, unknown>;
+  }
 
   // Archive guard: block writes on archived streams. Without this an append
   // would produce an "invisible" row that loadAggregate filters out by default
@@ -97,7 +113,7 @@ export async function appendDomainEventCore(
     tenantId: deps.tenantId,
     expectedVersion,
     type: args.type,
-    eventVersion: eventDef.version,
+    eventVersion: eventDef?.version ?? 1,
     payload: validatedPayload,
     metadata: {
       userId: deps.userId,