@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/src/pipeline/__tests__/tenant-timezone-cache.test.ts

@@ -1,89 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import type { TenantId } from "../../engine/types/identifiers";
-import { createTenantTimezoneCache } from "../tenant-timezone-cache";
-
-const tenantA = "tenant-a" as TenantId;
-const tenantB = "tenant-b" as TenantId;
-
-describe("TenantTimezoneCache", () => {
-  test("miss on an unset tenant", () => {
-    const cache = createTenantTimezoneCache();
-    expect(cache.get(tenantA)).toBeUndefined();
-  });
-
-  test("hit returns the cached value, including a cached 'no override' (undefined)", () => {
-    const cache = createTenantTimezoneCache();
-    cache.set(tenantA, "Asia/Tokyo");
-    cache.set(tenantB, undefined);
-
-    expect(cache.get(tenantA)).toEqual({ value: "Asia/Tokyo" });
-    // Distinct from a miss: tenantB was looked up and confirmed unset.
-    expect(cache.get(tenantB)).toEqual({ value: undefined });
-  });
-
-  test("invalidate() drops only the given tenant", () => {
-    const cache = createTenantTimezoneCache();
-    cache.set(tenantA, "Asia/Tokyo");
-    cache.set(tenantB, "Europe/Berlin");
-
-    cache.invalidate(tenantA);
-
-    expect(cache.get(tenantA)).toBeUndefined();
-    expect(cache.get(tenantB)).toEqual({ value: "Europe/Berlin" });
-  });
-
-  test("clear() drops every tenant", () => {
-    const cache = createTenantTimezoneCache();
-    cache.set(tenantA, "Asia/Tokyo");
-    cache.set(tenantB, "Europe/Berlin");
-
-    cache.clear();
-
-    expect(cache.size()).toBe(0);
-    expect(cache.get(tenantA)).toBeUndefined();
-    expect(cache.get(tenantB)).toBeUndefined();
-  });
-
-  test("entry expires after ttlMs", () => {
-    let t = 1_000_000;
-    const cache = createTenantTimezoneCache({ ttlMs: 1000, now: () => t });
-    cache.set(tenantA, "Asia/Tokyo");
-
-    expect(cache.get(tenantA)).toEqual({ value: "Asia/Tokyo" });
-
-    t += 1500;
-    expect(cache.get(tenantA)).toBeUndefined();
-  });
-
-  test("LRU: evicts oldest tenant when maxEntries is reached", () => {
-    const cache = createTenantTimezoneCache({ maxEntries: 2, ttlMs: 60_000 });
-    cache.set("a" as TenantId, "UTC");
-    cache.set("b" as TenantId, "UTC");
-    expect(cache.size()).toBe(2);
-
-    cache.set("c" as TenantId, "UTC");
-    expect(cache.size()).toBe(2);
-    expect(cache.get("a" as TenantId)).toBeUndefined();
-    expect(cache.get("c" as TenantId)).toEqual({ value: "UTC" });
-  });
-
-  test("LRU: touching an entry (get) moves it to the 'most recent' end", () => {
-    const cache = createTenantTimezoneCache({ maxEntries: 2, ttlMs: 60_000 });
-    cache.set("a" as TenantId, "UTC");
-    cache.set("b" as TenantId, "UTC");
-    cache.get("a" as TenantId); // touch a — b is now the oldest
-
-    cache.set("c" as TenantId, "UTC");
-
-    expect(cache.get("b" as TenantId)).toBeUndefined();
-    expect(cache.get("a" as TenantId)).toEqual({ value: "UTC" });
-  });
-
-  test("default maxEntries is 1000", () => {
-    const cache = createTenantTimezoneCache();
-    for (let i = 0; i < 1001; i++) {
-      cache.set(`tenant-${i}` as TenantId, "UTC");
-    }
-    expect(cache.size()).toBe(1000);
-  });
-});

package/src/pipeline/__tests__/try-append-event.integration.test.ts

@@ -1,168 +0,0 @@
-// Issue #1038 — ctx.tryAppendEvent (savepoint-scoped append).
-//
-// Claims pinned here:
-//   1. Happy path: first append on a fresh aggregate succeeds, returns
-//      { ok: true, event } with the stored event.
-//   2. Non-poisoning: when tryAppendEvent loses a version-conflict race, the
-//      rest of the handler's transaction still commits (a write AFTER the
-//      call in the same handler is not rolled back) — this is the whole
-//      reason the primitive exists over a bare try/catch around
-//      unsafeAppendEvent (Bun.SQL/postgres.js abort the entire begin() on
-//      an uncaught statement error, SQLSTATE 25P02, even if the JS error is
-//      caught).
-//
-// The conflict branch can't be forced deterministically through the public
-// interface — appendDomainEventCore reads the stream version fresh inside
-// itself, so a lone sequential append never conflicts; only two concurrent
-// transactions racing the same version produce the 23505. So claim 2 is
-// tested as an invariant over concurrent writers (looped per house
-// convention for probabilistic tests) rather than by asserting the conflict
-// branch was hit on a specific call — depending on interleaving, Postgres
-// may pick either writer as the winner.
-
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import * as z from "zod";
-import { createEventStoreExecutor } from "../../db/event-store-executor";
-import { asRawClient, selectMany } from "../../db/query";
-import { buildEntityTable } from "../../db/table-builder";
-import { createEntity, createTextField, defineFeature } from "../../engine";
-import { loadAggregate } from "../../event-store";
-import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
-
-const TAE_AGGREGATE_TYPE = "taeDoc";
-
-// Marker entity — a plain CRUD write issued right after ctx.tryAppendEvent
-// in the same handler/transaction. Its row landing (regardless of whether
-// the append won or lost the race) is the non-poisoning proof.
-const markerEntity = createEntity({
-  table: "tae_markers",
-  fields: {
-    note: createTextField({ personal: false, reason: "test_fixture", required: true }),
-  },
-});
-const markerTable = buildEntityTable("taeMarker", markerEntity);
-const markerExecutor = createEventStoreExecutor(markerTable, markerEntity, {
-  entityName: "taeMarker",
-});
-
-let stack: TestStack;
-const admin = TestUsers.admin;
-
-const tryAppendFeature = defineFeature("tae", (r) => {
-  r.entity("taeMarker", markerEntity);
-  const appended = r.defineEvent("appended", z.object({ note: z.string() }), {
-    piiFields: "none",
-  });
-
-  r.writeHandler(
-    "doc:try-append",
-    z.object({ aggregateId: z.uuid(), note: z.string() }),
-    async (event, ctx) => {
-      const result = await ctx.tryAppendEvent({
-        aggregateId: event.payload.aggregateId,
-        aggregateType: TAE_AGGREGATE_TYPE,
-        type: appended.name,
-        payload: { note: event.payload.note },
-      });
-      // Runs unconditionally — if tryAppendEvent's savepoint failed to
-      // confine the VersionConflictError, this write would fail too
-      // because the whole tx aborted (25P02).
-      const markerCreated = await markerExecutor.create(
-        { note: event.payload.note },
-        event.user,
-        ctx.db,
-      );
-      if (!markerCreated.isSuccess) return markerCreated;
-      return {
-        isSuccess: true as const,
-        data: {
-          ok: result.ok,
-          version: result.ok ? result.event.version : null,
-        },
-      };
-    },
-    { access: { roles: ["Admin"] } },
-  );
-});
-
-beforeAll(async () => {
-  stack = await setupTestStack({ features: [tryAppendFeature] });
-  await unsafeCreateEntityTable(stack.db, markerEntity, "taeMarker");
-});
-
-afterAll(async () => {
-  await stack.cleanup();
-});
-
-beforeEach(async () => {
-  await asRawClient(stack.db).unsafe(
-    `TRUNCATE kumiko_events, "${markerTable.tableName}" RESTART IDENTITY CASCADE`,
-  );
-});
-
-describe("Issue #1038 — ctx.tryAppendEvent", () => {
-  test("happy path: first append on a fresh aggregate returns { ok: true, event }", async () => {
-    const aggregateId = crypto.randomUUID();
-
-    const result = await stack.http.writeOk<{
-      ok: boolean;
-      version: number | null;
-    }>("tae:write:doc:try-append", { aggregateId, note: "hello" }, admin);
-
-    expect(result.ok).toBe(true);
-    expect(result.version).toBe(1);
-
-    const events = await loadAggregate(stack.db, aggregateId, admin.tenantId);
-    expect(events).toHaveLength(1);
-    expect(events[0]?.payload).toEqual({ note: "hello" });
-
-    const markers = await selectMany(stack.db, markerTable);
-    expect(markers).toHaveLength(1);
-  });
-
-  // Probabilistic — looped per house convention (mehrere Durchläufe, z.B.
-  // 20x) since a genuine 23505 race depends on transaction-timing
-  // interleaving that a single run can't force deterministically.
-  const ITERATIONS = 20;
-  const CONCURRENCY = 3;
-
-  test(`non-poisoning invariant holds across ${ITERATIONS} concurrent-writer rounds`, async () => {
-    for (let i = 0; i < ITERATIONS; i++) {
-      const aggregateId = crypto.randomUUID();
-
-      const responses = await Promise.all(
-        Array.from({ length: CONCURRENCY }, (_, n) =>
-          stack.http.write("tae:write:doc:try-append", { aggregateId, note: `writer-${n}` }, admin),
-        ),
-      );
-
-      // No writer's transaction was poisoned by a losing append — every
-      // request completes as a normal 200, never a 500 from an aborted tx.
-      let okCount = 0;
-      for (const res of responses) {
-        expect(res.status).toBe(200);
-        const body = (await res.json()) as { isSuccess: boolean; data: { ok: boolean } };
-        expect(body.isSuccess).toBe(true);
-        if (body.data.ok) okCount++;
-      }
-
-      // One event per successful append — interleaving-independent
-      // invariant. Serialized (non-racing) writers can legitimately all
-      // succeed at different versions; only actual conflicts return
-      // { ok: false }, so events.length must track okCount, not a fixed 1.
-      const events = await loadAggregate(stack.db, aggregateId, admin.tenantId);
-      expect(events).toHaveLength(okCount);
-      expect(okCount).toBeGreaterThanOrEqual(1);
-
-      // Every writer's marker insert landed regardless of win/lose — the
-      // savepoint confined the losers' VersionConflictError instead of
-      // aborting their whole transaction.
-      const markers = await selectMany(stack.db, markerTable);
-      expect(markers).toHaveLength(CONCURRENCY);
-
-      await asRawClient(stack.db).unsafe(
-        `TRUNCATE kumiko_events, "${markerTable.tableName}" RESTART IDENTITY CASCADE`,
-      );
-    }
-  });
-});

package/src/pipeline/__tests__/unsafe-raw-escape-hatch.integration.test.ts

@@ -1,103 +0,0 @@
-// fw#2858 — a write/query handler's `escapeHatch` also gates ctx.db.unsafeRaw(reason):
-// WITH it the raw query succeeds, WITHOUT it the same handler rejects with access_denied.
-// Real HTTP calls + setupTestStack — never createTestDispatcher. Modelled exactly on
-// escape-hatch.integration.test.ts (fw#2855).
-
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import * as z from "zod";
-import { executeRawQuery } from "../../db/queries/raw-sql";
-import { defineFeature } from "../../engine";
-import { createTestUser, setupTestStack, type TestStack } from "../../stack";
-
-const unsafeRawFeature = defineFeature("unsafe-raw-probe", (r) => {
-  r.writeHandler({
-    name: "write-with-hatch",
-    schema: z.object({}),
-    access: { roles: ["User"] },
-    escapeHatch: { reason: "fw#2858 integration test — declared unsafeRaw write" },
-    handler: async (_event, ctx) => {
-      const runner = ctx.db.unsafeRaw("fw#2858 integration test — declared unsafeRaw write");
-      const rows = await executeRawQuery<{ one: number }>(runner, "SELECT 1 AS one");
-      return { isSuccess: true as const, data: { one: rows[0]?.one } };
-    },
-  });
-
-  r.writeHandler({
-    name: "write-without-hatch",
-    schema: z.object({}),
-    access: { roles: ["User"] },
-    handler: async (_event, ctx) => {
-      const runner = ctx.db.unsafeRaw("no escapeHatch declared — must throw before this runs");
-      const rows = await executeRawQuery<{ one: number }>(runner, "SELECT 1 AS one");
-      return { isSuccess: true as const, data: { one: rows[0]?.one } };
-    },
-  });
-
-  r.queryHandler({
-    name: "query-with-hatch",
-    schema: z.object({}),
-    access: { roles: ["User"] },
-    escapeHatch: { reason: "fw#2858 integration test — declared unsafeRaw query" },
-    handler: async (_query, ctx) => {
-      const runner = ctx.db.unsafeRaw("fw#2858 integration test — declared unsafeRaw query");
-      const rows = await executeRawQuery<{ one: number }>(runner, "SELECT 1 AS one");
-      return { one: rows[0]?.one };
-    },
-  });
-
-  r.queryHandler({
-    name: "query-without-hatch",
-    schema: z.object({}),
-    access: { roles: ["User"] },
-    handler: async (_query, ctx) => {
-      const runner = ctx.db.unsafeRaw("no escapeHatch declared — must throw before this runs");
-      const rows = await executeRawQuery<{ one: number }>(runner, "SELECT 1 AS one");
-      return { one: rows[0]?.one };
-    },
-  });
-});
-
-let stack: TestStack;
-const user = createTestUser({
-  id: 92,
-  tenantId: "11111111-0000-4000-8000-000000000092",
-  roles: ["User"],
-});
-
-beforeAll(async () => {
-  stack = await setupTestStack({ features: [unsafeRawFeature] });
-});
-
-afterAll(async () => {
-  await stack.cleanup();
-});
-
-describe("write/query handler escapeHatch gates ctx.db.unsafeRaw()", () => {
-  test("write WITH escapeHatch: unsafeRaw succeeds", async () => {
-    const result = await stack.http.writeOk<{ one: number }>(
-      "unsafe-raw-probe:write:write-with-hatch",
-      {},
-      user,
-    );
-    expect(result.one).toBe(1);
-  });
-
-  test("write WITHOUT escapeHatch: unsafeRaw fails with access_denied", async () => {
-    const err = await stack.http.writeErr("unsafe-raw-probe:write:write-without-hatch", {}, user);
-    expect(err.code).toBe("access_denied");
-  });
-
-  test("query WITH escapeHatch: unsafeRaw succeeds", async () => {
-    const result = await stack.http.queryOk<{ one: number }>(
-      "unsafe-raw-probe:query:query-with-hatch",
-      {},
-      user,
-    );
-    expect(result.one).toBe(1);
-  });
-
-  test("query WITHOUT escapeHatch: unsafeRaw fails with access_denied", async () => {
-    const err = await stack.http.queryErr("unsafe-raw-probe:query:query-without-hatch", {}, user);
-    expect(err.code).toBe("access_denied");
-  });
-});

package/src/pipeline/active-membership.ts

@@ -1,190 +0,0 @@
-// One framework-owned composition of membership / principal-status /
-// tenant-lifecycle checks so login, switch-tenant and MFA completion can't independently drift.
-
-import type { DbConnection } from "../db/connection";
-import {
-  isPrincipalStatusPlugin,
-  isTenantLifecycleStatusPlugin,
-  type PrincipalStatusPlugin,
-  TENANT_TEARDOWN_STATUSES,
-  type TenantLifecycleStatusPlugin,
-} from "../engine/active-membership";
-import { EXT_PRINCIPAL_STATUS, EXT_TENANT_LIFECYCLE_STATUS } from "../engine/extension-names";
-import { createSystemUser } from "../engine/system-user";
-import type { ActiveMembershipResult, Registry } from "../engine/types";
-import type { TenantId } from "../engine/types/identifiers";
-import { InternalError } from "../errors";
-import { executeQuery } from "./dispatch-query";
-import { type DispatchContext, resolveDbSource } from "./dispatch-shared";
-import { rootWriteOrigin } from "./write-origin";
-
-export type ActiveMembershipPolicy = {
-  // destroyRequested still counts as active — owners must be able to cancel
-  // destruction; auth-middleware's own 410 gate then only admits that write.
-  readonly allowPendingDestruction: boolean;
-  // Whether a userId with no persisted principal row counts as active — a
-  // future background caller may instead want to fail closed.
-  readonly allowUnknownPrincipal: boolean;
-};
-
-export const INTERACTIVE_SIGN_IN_POLICY: ActiveMembershipPolicy = {
-  allowPendingDestruction: true,
-  allowUnknownPrincipal: true,
-};
-
-type RawMembershipRow = {
-  readonly tenantId: string;
-  readonly roles: readonly string[];
-  readonly tenantName?: string;
-  readonly tenantKey?: string;
-};
-
-// membershipQuery is a per-app-registered handler — engine-payload, not
-// trusted shape. Structural validation instead of a blind cast.
-function isMembershipRow(v: unknown): v is RawMembershipRow {
-  if (typeof v !== "object" || v === null) return false;
-  if (!("tenantId" in v) || typeof v.tenantId !== "string") return false;
-  if (!("roles" in v) || !Array.isArray(v.roles) || !v.roles.every((r) => typeof r === "string")) {
-    return false;
-  }
-  if ("tenantName" in v && v.tenantName !== undefined && typeof v.tenantName !== "string") {
-    return false;
-  }
-  if ("tenantKey" in v && v.tenantKey !== undefined && typeof v.tenantKey !== "string") {
-    return false;
-  }
-  return true;
-}
-
-async function findMembership(
-  ctx: DispatchContext,
-  userId: string,
-  tenantId: TenantId,
-): Promise<RawMembershipRow | undefined> {
-  const membershipUser = createSystemUser(tenantId);
-  // Auth-flow entry point with no enclosing handler, so it is its own root.
-  const rawMemberships = await executeQuery(
-    ctx,
-    ctx.membershipQuery,
-    { userId },
-    membershipUser,
-    rootWriteOrigin(ctx.registry, ctx.membershipQuery, membershipUser),
-  );
-  if (!Array.isArray(rawMemberships) || !rawMemberships.every(isMembershipRow)) {
-    throw new InternalError({
-      message:
-        `dispatcher.resolveActiveMembership: membershipQuery "${ctx.membershipQuery}" returned ` +
-        "a malformed result — expected an array of {tenantId, roles, tenantName?, tenantKey?} rows.",
-    });
-  }
-  return rawMemberships.find((m) => m.tenantId === tenantId);
-}
-
-// Exported so member-reader.ts (ctx.queryAsMember) can reach the registered
-// PrincipalStatusPlugin's resolveProfile without duplicating this lookup.
-export function resolvePrincipalPlugin(registry: Registry): PrincipalStatusPlugin {
-  const usages = registry.getExtensionUsages(EXT_PRINCIPAL_STATUS);
-  if (usages.length !== 1) {
-    throw new InternalError({
-      message:
-        usages.length === 0
-          ? `dispatcher.resolveActiveMembership: no "${EXT_PRINCIPAL_STATUS}" provider registered — mount the user feature.`
-          : `dispatcher.resolveActiveMembership: multiple "${EXT_PRINCIPAL_STATUS}" providers registered — exactly one is expected.`,
-    });
-  }
-  const usage = usages[0];
-  if (!usage || !isPrincipalStatusPlugin(usage.options)) {
-    throw new InternalError({
-      message: `dispatcher.resolveActiveMembership: "${usage?.entityName}" registered under "${EXT_PRINCIPAL_STATUS}" without a resolveStatus(userId, {db}) — extension options must be a PrincipalStatusPlugin.`,
-    });
-  }
-  return usage.options;
-}
-
-export function resolveTenantLifecyclePlugin(
-  registry: Registry,
-  caller: string,
-): TenantLifecycleStatusPlugin | undefined {
-  const usages = registry.getExtensionUsages(EXT_TENANT_LIFECYCLE_STATUS);
-  if (usages.length > 1) {
-    throw new InternalError({
-      message: `${caller}: multiple "${EXT_TENANT_LIFECYCLE_STATUS}" providers registered — exactly one (or zero) is expected.`,
-    });
-  }
-  const usage = usages[0];
-  if (!usage) return undefined;
-  if (!isTenantLifecycleStatusPlugin(usage.options)) {
-    throw new InternalError({
-      message: `${caller}: "${usage.entityName}" registered under "${EXT_TENANT_LIFECYCLE_STATUS}" without a resolveStatus(tenantId, {db}) — extension options must be a TenantLifecycleStatusPlugin.`,
-    });
-  }
-  return usage.options;
-}
-
-function isTeardownRejected(
-  status: { readonly status: string } | null,
-  policy: ActiveMembershipPolicy,
-): boolean {
-  return (
-    status !== null &&
-    TENANT_TEARDOWN_STATUSES.has(status.status) &&
-    !(status.status === "destroyRequested" && policy.allowPendingDestruction)
-  );
-}
-
-// Order is load-bearing: a non-member must never learn a foreign tenant's
-// lifecycle/blocked state, so membership is resolved and checked FIRST.
-export async function resolveActiveMembershipFn(
-  ctx: DispatchContext,
-  userId: string,
-  tenantId: TenantId,
-  policy: ActiveMembershipPolicy,
-): Promise<ActiveMembershipResult> {
-  const { registry } = ctx;
-
-  const membership = await findMembership(ctx, userId, tenantId);
-  if (!membership) {
-    return { kind: "rejected", reason: "not_a_member" };
-  }
-
-  const principalPlugin = resolvePrincipalPlugin(registry);
-  const dbSource = resolveDbSource(ctx, undefined);
-  if (!dbSource) {
-    throw new InternalError({
-      message:
-        "dispatcher.resolveActiveMembership requires a database connection — none is configured.",
-    });
-  }
-  // resolveDbSource(ctx, undefined) never returns a tx, only AppContext.db —
-  // the dispatcher boundary holds that as the root DbConnection, same as buildAuthClaimsContext.
-  const db = dbSource as DbConnection; // @cast-boundary db-operator
-
-  const principalStatus = await principalPlugin.resolveStatus(userId, { db });
-  if (
-    principalStatus === "blocked" ||
-    (principalStatus === "unknown" && !policy.allowUnknownPrincipal)
-  ) {
-    return { kind: "rejected", reason: "principal_blocked" };
-  }
-
-  const lifecyclePlugin = resolveTenantLifecyclePlugin(
-    registry,
-    "dispatcher.resolveActiveMembership",
-  );
-  if (lifecyclePlugin) {
-    const lifecycle = await lifecyclePlugin.resolveStatus(tenantId, { db });
-    if (isTeardownRejected(lifecycle, policy)) {
-      return { kind: "rejected", reason: "tenant_teardown" };
-    }
-  }
-
-  return {
-    kind: "active",
-    membership: {
-      tenantId,
-      roles: membership.roles,
-      ...(membership.tenantName !== undefined ? { tenantName: membership.tenantName } : {}),
-      ...(membership.tenantKey !== undefined ? { tenantKey: membership.tenantKey } : {}),
-    },
-  };
-}

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

@@ -1,117 +0,0 @@
-import { requestContext } from "../api/request-context";
-import { SYSTEM_EVENT_PREFIX } from "../crypto/system-event-pii";
-import type { DbRunner } from "../db/connection";
-import { qnScope, toKebab } from "../engine/qualified-name";
-import type { AppendEventArgs, Registry, TenantId } from "../engine/types";
-import { InternalError, validationErrorFromZod } from "../errors";
-import { isStreamArchived } from "../event-store/archive";
-import { ArchivedStreamError } from "../event-store/errors";
-import { append, getStreamVersion, type StoredEvent } from "../event-store/event-store";
-import { runProjectionsForEvent } from "./projections-runner";
-
-// Shared append-pipeline: Schema-validate → archive-guard → stream-version →
-// append → inline-projections. One implementation for both
-// `dispatcher.appendDomainEvent` (write-handler `ctx.appendEvent`) and
-// `multi-stream-apply-context.appendEvent` (MSP-apply-side). Both call-sites
-// differ only in where `userId` comes from (SessionUser vs. triggering event
-// metadata) — everything after that is identical.
-export type AppendDomainEventCoreDeps = {
-  readonly registry: Registry;
-  readonly db: DbRunner;
-  readonly tenantId: TenantId;
-  // stringified user id — executor and dispatcher differ in their SessionUser
-  // typing, so we normalise at the boundary.
-  readonly userId: string;
-  // Label for the "event not registered" error message so the failure points
-  // at the caller (e.g. "ctx.appendEvent" vs. "MSP-apply ctx.appendEvent").
-  readonly callSiteLabel: string;
-  // Feature that issued the append — used to enforce cross-feature ownership:
-  // events are owned by the feature that r.defineEvent'd them. When provided,
-  // appendDomainEventCore rejects any args.type whose feature-prefix does not
-  // match this caller. Omit for internal framework calls that legitimately
-  // cross features.
-  readonly callerFeature?: string;
-};
-
-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 && !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>").`,
-    });
-  }
-  // Cross-feature ownership: features don't get to emit each other's events.
-  // Silent cross-feature writes would make event-store semantics fragile —
-  // a rename or schema-evolution in feature A could break an unrelated
-  // handler in feature B. The contract is: if you want feature A's state to
-  // react to feature B, wire an r.multiStreamProjection in A against B's
-  // events and let A emit its OWN follow-up on A's stream.
-  //
-  // 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 && !isSystemEvent) {
-    const owner = qnScope(args.type);
-    const callerKebab = toKebab(deps.callerFeature);
-    if (owner && owner !== callerKebab) {
-      throw new InternalError({
-        message: `${deps.callSiteLabel}("${args.type}") — event belongs to feature "${owner}" but the caller runs in feature "${callerKebab}". Events are owned by the feature that defines them. Either move r.defineEvent into "${callerKebab}", or react via r.multiStreamProjection and emit a follow-up event you own.`,
-      });
-    }
-  }
-  // 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
-  // — silent data loss from the caller's POV.
-  if (await isStreamArchived(deps.db, deps.tenantId, args.aggregateId)) {
-    throw new ArchivedStreamError(deps.tenantId, args.aggregateId);
-  }
-
-  // Stream-version authoritative. See Block 0 / getStreamVersion doc for
-  // why row.version isn't sufficient once ctx.appendEvent enters the picture.
-  const expectedVersion = await getStreamVersion(deps.db, args.aggregateId, deps.tenantId);
-
-  const reqCtx = requestContext.get();
-  // metadata.requestId is a plain trace marker — no uniqueness constraint,
-  // every event of the request carries it. HTTP-level idempotency runs in
-  // pipeline/idempotency.ts (Redis-backed cached-response replay) BEFORE
-  // the command executes, so retries never reach this code path twice for
-  // the same request.
-  const stored = await append(deps.db, {
-    aggregateId: args.aggregateId,
-    aggregateType: args.aggregateType,
-    tenantId: deps.tenantId,
-    expectedVersion,
-    type: args.type,
-    eventVersion: eventDef?.version ?? 1,
-    payload: validatedPayload,
-    metadata: {
-      userId: deps.userId,
-      ...(reqCtx?.requestId ? { requestId: reqCtx.requestId } : {}),
-      ...(reqCtx?.correlationId ? { correlationId: reqCtx.correlationId } : {}),
-      ...(reqCtx?.causationId ? { causationId: reqCtx.causationId } : {}),
-      ...(args.headers ? { headers: args.headers } : {}),
-    },
-  });
-
-  // Inline projections fire in the same tx — a throw rolls everything back
-  // together. Same semantics regardless of which call-site triggered the
-  // append (write-handler ctx.appendEvent vs. MSP-apply ctx.appendEvent).
-  await runProjectionsForEvent(stored, deps.registry, deps.db);
-
-  return stored;
-}