@cosmicdrift/kumiko-framework 0.320.0 → 0.322.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.320.0",
+  "version": "0.322.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>",
@@ -202,8 +202,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.320.0",
-    "@cosmicdrift/kumiko-types": "0.320.0",
+    "@cosmicdrift/kumiko-http": "0.322.0",
+    "@cosmicdrift/kumiko-types": "0.322.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -219,7 +219,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.320.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.322.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -54,6 +54,17 @@ describe("runSchemaCli — no-DB paths", () => {
     expect(cap.err).toHaveLength(0);
   });
 
+  test.each(["--help", "-h", "help"])(
+    "%s prints the same usage as no subcommand and exits 0",
+    async (helpArg) => {
+      const cap = captureOut();
+      const code = await runSchemaCli([helpArg], appCwd, cap.out);
+      expect(code).toBe(0);
+      expect(cap.log.join("\n")).toContain("Subcommands:");
+      expect(cap.err).toHaveLength(0);
+    },
+  );
+
   test("unknown subcommand exits 1 and reports it on stderr", async () => {
     const cap = captureOut();
     const code = await runSchemaCli(["cutover"], appCwd, cap.out);

package/src/__tests__/upgrade-cli.test.ts

@@ -14,8 +14,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   findCodemodScriptsRoot,
-  findCoreChangelogFile,
   findFeaturesDirs,
+  findPackageChangelogFiles,
   resolveCodemodScript,
   runUpgradeCli,
   type UpgradeCliOut,
@@ -92,6 +92,23 @@ async function runJson(cwd: string, from: string): Promise<{ pending: Array<{ ti
   return JSON.parse(spy.logs.join("\n"));
 }
 
+describe("upgrade command — --help", () => {
+  test("--help prints usage and exits 0 without touching the filesystem", async () => {
+    const spy = makeSpyOutput();
+    const exit = await runUpgradeCli(["--help"], "/nonexistent-cwd", spy.out);
+    expect(exit).toBe(0);
+    expect(spy.logs.join("\n")).toContain("kumiko-upgrade");
+    expect(spy.errs).toEqual([]);
+  });
+
+  test("-h behaves the same as --help", async () => {
+    const spy = makeSpyOutput();
+    const exit = await runUpgradeCli(["-h"], "/nonexistent-cwd", spy.out);
+    expect(exit).toBe(0);
+    expect(spy.logs.join("\n")).toContain("--apply");
+  });
+});
+
 describe("upgrade command — framework core changelog", () => {
   test("collects core changes.json from the framework repo layout", async () => {
     const cwd = tmp({
@@ -198,6 +215,37 @@ describe("upgrade command — framework core changelog", () => {
   });
 });
 
+describe("upgrade command — every package's changelog, not just framework core", () => {
+  const SERVER_RUNTIME_ENTRY = JSON.stringify([
+    { version: "0.168.0", type: "breaking", title: "server-runtime breaking change" },
+  ]);
+
+  test("a hoisted non-framework, non-bundled-features package's changes.json shows up in pending", async () => {
+    const cwd = tmp({
+      "node_modules/@cosmicdrift/kumiko-server-runtime/src/changes.json": SERVER_RUNTIME_ENTRY,
+      "apps/web/package.json": "{}",
+    });
+
+    const result = await runJson(`${cwd}/apps/web`, "0.165.0");
+
+    expect(result.pending.map((e) => e.title)).toEqual(["server-runtime breaking change"]);
+  });
+
+  test("bundled-features is never double-counted alongside findFeaturesDirs's own collection", async () => {
+    const cwd = tmp({
+      "node_modules/@cosmicdrift/kumiko-server-runtime/src/changes.json": SERVER_RUNTIME_ENTRY,
+      "node_modules/@cosmicdrift/kumiko-bundled-features/src/user/changes.json": FEATURE_ENTRY,
+      "apps/web/package.json": "{}",
+    });
+
+    const result = await runJson(`${cwd}/apps/web`, "0.165.0");
+
+    expect(result.pending.map((e) => e.title).sort()).toEqual(
+      ["feature fix", "server-runtime breaking change"].sort(),
+    );
+  });
+});
+
 describe("upgrade command — enterprise package layout", () => {
   // Layout is detected by presence of changes.json, not an "ai-" name
   // prefix — the old heuristic silently dropped every enterprise package
@@ -641,9 +689,8 @@ describe("changes.json codemod fields resolve to real published scripts", () =>
   }
 
   test("every codemod field is a scripts/codemod/*.ts path that resolves to an existing published script", () => {
-    const coreChangelog = findCoreChangelogFile(REAL_REPO_ROOT);
     const changesJsonFiles = [
-      ...(coreChangelog ? [coreChangelog] : []),
+      ...findPackageChangelogFiles(REAL_REPO_ROOT),
       ...findFeaturesDirs(REAL_REPO_ROOT).flatMap((dir) => findChangesJsonFiles(dir)),
     ];
     expect(changesJsonFiles.length).toBeGreaterThan(0);

package/src/api/__tests__/client-ip.test.ts

@@ -9,6 +9,7 @@ import {
   assertValidTrustedProxyHops,
   type ClientIpHeaderSource,
   createClientIpResolver,
+  parseTrustedProxyHopsEnv,
 } from "../client-ip";
 
 function sourceOf(headers: Record<string, string>, socketAddress?: string): ClientIpHeaderSource {
@@ -137,3 +138,27 @@ describe("createClientIpResolver", () => {
     expect(() => createClientIpResolver(-1, "test")).toThrow(/non-negative integer/);
   });
 });
+
+describe("parseTrustedProxyHopsEnv", () => {
+  test("undefined -> undefined (no env set)", () => {
+    expect(parseTrustedProxyHopsEnv(undefined, "test")).toBeUndefined();
+  });
+
+  test("valid digits-only string -> parsed integer", () => {
+    expect(parseTrustedProxyHopsEnv("1", "test")).toBe(1);
+    expect(parseTrustedProxyHopsEnv("0", "test")).toBe(0);
+    expect(parseTrustedProxyHopsEnv("42", "test")).toBe(42);
+  });
+
+  test("hex/exponent/negative notation throws instead of silently coercing", () => {
+    expect(() => parseTrustedProxyHopsEnv("0x10", "test")).toThrow(/non-negative integer/);
+    expect(() => parseTrustedProxyHopsEnv("1e3", "test")).toThrow(/non-negative integer/);
+    expect(() => parseTrustedProxyHopsEnv("-1", "test")).toThrow(/non-negative integer/);
+  });
+
+  test("error message carries the context prefix and the raw value", () => {
+    expect(() => parseTrustedProxyHopsEnv("x", "runProdApp")).toThrow(
+      'runProdApp: KUMIKO_TRUSTED_PROXY_HOPS must be a non-negative integer, got "x".',
+    );
+  });
+});

package/src/api/__tests__/extra-routes.integration.test.ts

@@ -585,6 +585,48 @@ describe("extraRoutes: entry:signature", () => {
   });
 });
 
+describe("extraRoutes: entry:anonymous deps.clientIp", () => {
+  const clientIpRoute: AnonymousExtraRoute = {
+    method: "GET",
+    path: "/public/client-ip-probe",
+    entry: "anonymous",
+    handler: async (c, deps) => c.json({ clientIp: deps.clientIp }),
+  };
+
+  test("default trustedProxyHops (0): a spoofed X-Forwarded-For is ignored, socket address wins", async () => {
+    const stack = await setupTestStack({
+      features: [probeFeature],
+      extraRoutes: [clientIpRoute],
+    });
+    try {
+      const res = await stack.app.request(
+        "/public/client-ip-probe",
+        { headers: { "x-forwarded-for": "203.0.113.10" } },
+        "198.51.100.9",
+      );
+      expect(await res.json()).toEqual({ clientIp: "198.51.100.9" });
+    } finally {
+      await stack.cleanup();
+    }
+  });
+
+  test("trustedProxyHops: 1 — the rightmost X-Forwarded-For entry is trusted", async () => {
+    const stack = await setupTestStack({
+      features: [probeFeature],
+      extraRoutes: [clientIpRoute],
+      trustedProxyHops: 1,
+    });
+    try {
+      const res = await stack.app.request("/public/client-ip-probe", {
+        headers: { "x-forwarded-for": "203.0.113.10" },
+      });
+      expect(await res.json()).toEqual({ clientIp: "203.0.113.10" });
+    } finally {
+      await stack.cleanup();
+    }
+  });
+});
+
 // Type-level contract for ExtraRouteDefinition (kumiko-framework#3050): the
 // bodies below are never invoked — tsc checks them, bun:test does not run
 // them. Each `@ts-expect-error` turns into an "unused directive" compile

package/src/api/client-ip.ts

@@ -44,6 +44,33 @@ export function assertValidTrustedProxyHops(value: number | undefined, context:
   }
 }
 
+export const TRUSTED_PROXY_HOPS_ENV = "KUMIKO_TRUSTED_PROXY_HOPS";
+
+// Fail loud on a garbage env value rather than silently coercing to NaN:
+// a resolver built from NaN treats it like "always short chain" and returns
+// "unknown" for every request, which collapses an IP-keyed rate limiter
+// into one shared bucket for the whole deployment — a self-inflicted DoS,
+// worse than staying on the default. Digits-only (not parseInt) —
+// parseInt("0x10")/("1e3")/("2x") would silently coerce instead of failing.
+export function parseTrustedProxyHopsEnv(
+  raw: string | undefined,
+  context: string,
+): number | undefined {
+  if (raw === undefined) return undefined;
+  if (!/^\d+$/.test(raw)) {
+    throw new Error(
+      `${context}: ${TRUSTED_PROXY_HOPS_ENV} must be a non-negative integer, got "${raw}".`,
+    );
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(
+      `${context}: ${TRUSTED_PROXY_HOPS_ENV} must be a non-negative integer, got "${raw}".`,
+    );
+  }
+  return parsed;
+}
+
 // Instance-scoped, NOT a module singleton: the warn-once flag must reset
 // per server boot (and per test), otherwise the first test to trigger it
 // consumes the warning for the whole process and later tests can't observe

package/src/api/extra-route.ts

@@ -32,6 +32,9 @@ export type AnonymousExtraRouteDeps = {
    *  user, same request-resolved tenant (never overridable), only under
    *  "/api/" (the only path that populates a session user). */
   readonly write: (type: string, payload: unknown) => Promise<WriteResult>;
+  /** Resolved by the server's single trustedProxyHops-aware resolver —
+   *  never read X-Forwarded-For yourself. */
+  readonly clientIp: string;
 };
 
 export type AnonymousExtraRoute = {

package/src/api/index.ts

@@ -34,6 +34,8 @@ export {
   clientIpSourceFromHonoContext,
   createClientIpResolver,
   extractSocketAddress,
+  parseTrustedProxyHopsEnv,
+  TRUSTED_PROXY_HOPS_ENV,
   UNKNOWN_CLIENT_IP,
 } from "./client-ip";
 export type {
@@ -73,7 +75,11 @@ export type {
 export { isSafeLandingPath } from "./post-auth-landing";
 export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker } from "./redis-sse-broker";
-export { type RequestContextData, requestContext } from "./request-context";
+export {
+  type RequestContextData,
+  requestContext,
+  runAsDirectCallEntry,
+} from "./request-context";
 export {
   buildRequestContextDataFromRequest,
   requestIdMiddleware,

package/src/api/request-context.ts

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { isPersonalDataGated, type WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
+import type { AgentRisk } from "@cosmicdrift/kumiko-types/handlers";
 import { generateId } from "../utils";
 
 // Request-scoped propagation. Populated by the HTTP middleware and by the
@@ -54,6 +55,10 @@ export type RequestContextData = {
   // Only ever a gated origin. Read by job enqueue and event-store.append();
   // dispatch roots never narrow from it, only jobs inherit explicitly.
   readonly writeOrigin?: WriteOrigin;
+  // The handler directly invoked by the dispatcher (not a nested ctx.write/
+  // writeAs target) — nested dispatches inherit it unchanged, so the
+  // irreversible-operation gate always sees the outermost caller's risk.
+  readonly entryHandler?: { readonly qn: string; readonly risk: AgentRisk };
 };
 
 const storage = new AsyncLocalStorage<RequestContextData>();
@@ -77,7 +82,11 @@ export const requestContext = {
 // when there is no surrounding request (job-runner, event-dispatcher) —
 // requestId/correlationId are mandatory, `get()` may be undefined.
 export function runWithOrigin<T>(
-  origin: { readonly feature?: string; readonly handler?: string },
+  origin: {
+    readonly feature?: string;
+    readonly handler?: string;
+    readonly entryHandler?: { readonly qn: string; readonly risk: AgentRisk };
+  },
   fn: () => T,
 ): T {
   const current = requestContext.get();
@@ -89,11 +98,24 @@ export function runWithOrigin<T>(
       correlationId: current?.correlationId ?? requestId,
       feature: origin.feature,
       handler: origin.handler,
+      // The outermost dispatch wins — a nested ctx.write/writeAs must not
+      // overwrite the entry handler that the irreversible-operation gate reads.
+      entryHandler: current?.entryHandler ?? origin.entryHandler,
     },
     fn,
   );
 }
 
+// Clears entryHandler so the next dispatch inside fn becomes the new entry —
+// used by dispatchToolCall so the invoked tool handler, not the surrounding
+// turn/approve handler, is what the irreversible-operation gate sees.
+export function runAsDirectCallEntry<T>(fn: () => T): T {
+  const current = requestContext.get();
+  if (!current) return fn();
+  const { entryHandler: _entryHandler, ...rest } = current;
+  return requestContext.run(rest, fn);
+}
+
 // An ungated origin never mints a scope: seeds and boot writes keep their missing context.
 export function runWithWriteOrigin<T>(origin: WriteOrigin, fn: () => T): T {
   const current = requestContext.get();

package/src/api/server.ts

@@ -617,6 +617,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
         userId: event.metadata.userId,
         ...(mspOwner && { callerFeature: mspOwner }),
         ...(mspFiles && { files: mspFiles }),
+        ...(contextWithObservability.secrets && { secrets: contextWithObservability.secrets }),
         ...(mspFiles && {
           derivatives: createDerivativesContext({
             files: mspFiles,
@@ -1260,7 +1261,7 @@ type ExtraRouteHonoHandlerDeps = {
   readonly secrets: import("../secrets").SecretsContext | undefined;
   readonly dispatchSystemWrite: (args: SystemDispatchArgs) => Promise<WriteResult>;
   readonly dispatchSystemQuery: (args: SystemDispatchArgs) => Promise<unknown>;
-  readonly clientIpResolver?: ClientIpResolver;
+  readonly clientIpResolver: ClientIpResolver;
 };
 
 function buildExtraRouteHonoHandler(
@@ -1276,6 +1277,7 @@ function buildExtraRouteHonoHandler(
           registry: shared.registry,
           systemQuery: makeSystemQuery(c, shared.dispatcher, shared.clientIpResolver),
           write: makeAnonymousWrite(c, shared.dispatcher),
+          clientIp: shared.clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
         });
     case ExtraRouteEntries.user:
       return async (c) => {

package/src/changes.json

@@ -1,4 +1,64 @@
 [
+  {
+    "version": "0.322.0",
+    "type": "breaking",
+    "title": "Irreversible writes now require agent.risk \"high\" on the directly-dispatched handler",
+    "migration": "Any write handler reachable as the directly-dispatched entry point that\nperforms `executor.forget()` (any entity) or `executor.delete()` on an\nentity without `softDelete` must resolve `agent.risk: \"high\"`, or the\nexecutor gate now denies it with `access_denied` /\n`irreversible_operation_requires_high_risk` before any DB read.\n\nThree breaking changes ship together:\n1. Add `agent: { risk: \"high\" }` to your own write handler if it directly\n   runs `forget` or a hard `delete` on a non-softDelete entity.\n2. Delegating via `ctx.write`/`ctx.writeAs` from a lower-risk handler into\n   a high-risk forget/hard-delete handler no longer inherits the inner\n   handler's risk — the outermost/entry handler's declared risk governs,\n   so the delegating handler itself must be \"high\".\n3. Declaring `agent.risk` below \"high\" on a standard entity-convention\n   delete handler for a non-softDelete entity is now a define-time/boot\n   error instead of a silently-accepted setting.\n\nStandard entity-convention delete handlers on a non-softDelete entity now\ndefault to \"high\" automatically (no more implicit \"always allow\").\n\n`dispatchToolCall` treats the invoked tool itself as the entry handler,\nnot the surrounding turn/approve write handler that dispatched it — a\nmid-risk \"approve\" handler can safely invoke a high-risk tool directly,\nbut a mid-risk tool that itself delegates to a high-risk handler via\n`ctx.write`/`writeAs` is still denied per rule 2.\n\n`runAsDirectCallEntry` (framework `/api`) is the one sanctioned entry\nboundary: it clears the entry handler so the next dispatch counts as the\ndirectly called one. `dispatchToolCall` uses it because the human\nconfirmation happens in approve; do not use it to lift a handler past\nthe floor.\n\nRemaining gap: `afterCommit` hooks, jobs, and event consumers are not\ngated by this floor — they have no directly-dispatched entry handler to\nattribute risk to."
+  },
+  {
+    "version": "0.322.0",
+    "type": "improvement",
+    "title": "Translation values may now be CLDR plural-form objects, resolved per locale with Intl.PluralRules",
+    "migration": "A translation entry's value type widens from `string` to\n`string | PluralForms`, so an existing `TranslationEntry` locale value can\nnow also be an object with `one`/`few`/`many`/`other` (etc.) CLDR\ncategories, where `other` is required:\n\n```ts\n{ de: { one: \"{count} Status-Seite\", other: \"{count} Status-Seiten\" } }\n```\n\n`createI18n(...).t(key, locale, { count })` resolves the CLDR category for\nthe given locale via a per-locale-cached `Intl.PluralRules` and interpolates\n`{count}`; it falls back to `other` when `count` is missing/non-finite, the\nlocale tag is invalid, or `Intl.PluralRules` is unavailable (older Hermes).\n`mailT` and the renderer's `translateWithFallbacks` resolve plural values\nthe same way, through the shared `resolveTranslationValue` helper.\n\nExisting string-only translations keep working unchanged. Code that reads\nvalues back out of a bundle (`TranslationBundle`, `TranslationsByLocale`,\n`TranslationEntry`) and annotates them as `string` no longer typechecks:\nannotate as `TranslationValue` (from `@cosmicdrift/kumiko-framework/ui-types`)\nor flatten with `translationValueOtherText(value)`."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "kumiko-schema gained --help/-h/help",
+    "detail": "Prints usage listing the available subcommands and exits 0.",
+    "migration": "No action needed."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "parseTrustedProxyHopsEnv/TRUSTED_PROXY_HOPS_ENV factored out of runProdApp for runDevApp and consumer tooling to share",
+    "detail": "`packages/framework/src/api/client-ip.ts` gained\n`parseTrustedProxyHopsEnv(raw, context)` and the\n`TRUSTED_PROXY_HOPS_ENV = \"KUMIKO_TRUSTED_PROXY_HOPS\"` constant (both\nexported via the `api` barrel), moved out of `runProdApp`'s inline\nparsing. Same validation and error message as before.",
+    "migration": "No action needed; runProdApp's behavior and error message are unchanged."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "AnonymousExtraRouteDeps gained clientIp, resolved by the server's trustedProxyHops-aware resolver",
+    "detail": "`AnonymousExtraRouteDeps.clientIp: string`, populated the same way as the\nhttpRoute path via `shared.clientIpResolver.resolve\n(clientIpSourceFromHonoContext(c))`. `ExtraRouteHonoHandlerDeps\n.clientIpResolver` is now required (its only caller always supplied it).",
+    "migration": "Anonymous extra routes that need the caller's IP should read\n`deps.clientIp` instead of reading `X-Forwarded-For` (or any other\nheader) themselves — the latter is attacker-controlled unless you also\nknow the exact trusted-hop count. Tests that build an\n`AnonymousExtraRouteDeps` literal by hand must add a `clientIp` string."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "feature-ast resolves imported constants and registrar wrappers without building a TypeScript program",
+    "detail": "Imported `const` initializers (named imports, aliases, `export { X as Y }`,\nre-export chains, `export *`) and imported registrar-wrapper functions are\nresolved through `ts.resolveModuleName` plus a syntactic export walk.\nSame-file lookups walk enclosing block scopes instead of the file top level. Parse\noutput is unchanged; parsing a feature file drops from hundreds of\nmilliseconds to a few milliseconds."
+  },
+  {
+    "version": "0.321.0",
+    "type": "breaking",
+    "title": "webhook.send step auth secretRef renamed to secret; MultiStreamApplyContext gained an optional secrets field",
+    "detail": "`r.step.webhook.send`'s `auth` union renamed `secretRef` → `secret` (see\nthe step-dispatcher entry for the full rationale). `MultiStreamApplyContext`\n(and `createMultiStreamApplyContext`'s deps) gained an optional\n`secrets?: SecretsContext` field, mirroring `files`/`derivatives` — present\nwhen the app booted with the secrets feature, letting a saga/process-\nmanager MSP apply read a tenant secret with its own audit context. The\nserver's MSP consumer wiring now threads the boot-time `AppContext.secrets`\nthrough automatically; `rebuildMultiStreamProjection`'s rebuild context\ndeliberately does not carry `secrets` (rebuild must stay side-effect-free).",
+    "migration": "Rename `auth.secretRef` → `auth.secret` at every `r.step.webhook.send`\ncall site. No action needed for `MultiStreamApplyContext` consumers that\ndon't read `ctx.secrets` — the field is optional and additive."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "New event-store primitive transferAggregateStreams for tenant-to-tenant aggregate moves",
+    "detail": "`transferAggregateStreams(db, { sourceTenantId, destinationTenantId,\naggregateType, aggregateIds, transferredBy })` (event-store/transfer.ts)\nmoves an aggregate's events, drops its snapshot, and carries its archive\nmarker from one tenant to another, then appends one\n`kumiko:system:aggregate.transferred` system event per moved aggregate\n(own fresh stream, destination tenant, payload carries aggregateType/\naggregateId/sourceTenantId/destinationTenantId). An id with no events\nunder the given tenant/aggregateType is left untouched and gets no event.\nBacked by db/queries/event-store-transfer.ts.",
+    "migration": "No action for existing consumers — this is a new, additive primitive."
+  },
+  {
+    "version": "0.321.0",
+    "type": "fix",
+    "title": "upgrade-cli now collects every package's changes.json, not just framework's",
+    "detail": "`findCoreChangelogFile(cwd): string | null` is replaced by\n`findPackageChangelogFiles(cwd): string[]`. In the framework repo itself\nit collects every `packages/<dir>/src/changes.json` except\n`packages/bundled-features` (bundled features are already collected per\nfeature dir). In a consumer repo it walks up to 10 levels looking for\n`node_modules/@cosmicdrift/*/src/changes.json`, skipping\n`kumiko-bundled-features`, deduping by package name (nearest\n`node_modules` wins) and by realpath (symlinked workspace copies).",
+    "migration": "No action needed — `kumiko upgrade` now surfaces more relevant breaking\nchanges than before, it never hides ones it previously showed."
+  },
   {
     "version": "0.320.0",
     "type": "breaking",

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

@@ -18,6 +18,10 @@ import {
   VersionConflictError as EventStoreVersionConflict,
   getStreamVersion,
 } from "../event-store";
+import {
+  assertIrreversibleOperationAllowed,
+  isIrreversibleEntityVerb,
+} from "../pipeline/irreversible-operation-gate";
 import { generateId } from "../utils";
 import { applyEntityEvent } from "./apply-entity-event";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
@@ -586,6 +590,9 @@ export function createWriteVerbs(
     },
 
     async delete(payload, user, db) {
+      if (isIrreversibleEntityVerb("delete", entity)) {
+        assertIrreversibleOperationAllowed(`${entityName}.delete (entity has no softDelete)`);
+      }
       const runner = tenantDbRunner(db);
       const existing = await loadById(payload.id, db);
       if (!existing) return writeFailure(new NotFoundError(entityName, payload.id));
@@ -684,6 +691,7 @@ export function createWriteVerbs(
     // the erasure replays on rebuild (created → forgotten → row gone). Loads
     // without the isDeleted filter so trashed (soft-deleted) rows are erased too.
     async forget(payload, user, db) {
+      assertIrreversibleOperationAllowed(`${entityName}.forget`);
       const runner = tenantDbRunner(db);
       const raw = await db.fetchOne<Record<string, unknown>>(table, { id: payload.id });
       if (!raw) return writeFailure(new NotFoundError(entityName, payload.id));

package/src/db/queries/event-store-transfer.ts

@@ -0,0 +1,73 @@
+// Raw SQL backing event-store/transfer.ts — the framework's own tenant-transfer
+// primitive for streams. Kept in db/queries alongside the rest of the
+// event-store's raw statements (see event-store.ts, event-store-admin.ts,
+// backfill-pii.ts): the one place in the repo allowed to write tenant_id
+// directly onto kumiko_events / kumiko_snapshots / kumiko_archived_streams.
+
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+export type TransferEventRowsParams = {
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+  readonly aggregateType: string;
+  readonly aggregateIds: readonly string[];
+};
+
+// Postgres' RETURNING clause has no DISTINCT keyword — dedupe the
+// per-event-row hits in-process instead of relying on invalid SQL.
+export async function transferEventRows(
+  db: AnyDb,
+  params: TransferEventRowsParams,
+): Promise<readonly string[]> {
+  const rows = (await asRawClient(db).unsafe(
+    `UPDATE "kumiko_events" SET "tenant_id" = $1 ` +
+      `WHERE "tenant_id" = $2 AND "aggregate_type" = $3 AND "aggregate_id" = ANY($4) ` +
+      `RETURNING "aggregate_id" AS id`,
+    [params.destinationTenantId, params.sourceTenantId, params.aggregateType, params.aggregateIds],
+  )) as ReadonlyArray<{ id: string }>;
+  return [...new Set(rows.map((row) => row.id))];
+}
+
+export type DeleteSnapshotsForAggregatesParams = {
+  readonly tenantId: string;
+  readonly aggregateIds: readonly string[];
+};
+
+// Snapshots are a pure read-performance cache (event-store/snapshot.ts) —
+// dropped rather than rewritten, forcing a full replay from the just-moved
+// events on next read instead of carrying the snapshot's own generation
+// bookkeeping across the tenant boundary.
+export async function deleteSnapshotsForAggregates(
+  db: AnyDb,
+  params: DeleteSnapshotsForAggregatesParams,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `DELETE FROM "kumiko_snapshots" WHERE "tenant_id" = $1 AND "aggregate_id" = ANY($2)`,
+    [params.tenantId, params.aggregateIds],
+  );
+}
+
+export type TransferArchivedStreamRowsParams = {
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+  readonly aggregateType: string;
+  readonly aggregateIds: readonly string[];
+};
+
+// An archived stream's marker must move with it — leaving it behind would
+// make the stream writable again the instant it lands in the destination
+// tenant (archive.ts's isStreamArchived check is itself tenant-scoped).
+// `aggregate_type` is part of the match, same as transferEventRows — an
+// archived marker for a DIFFERENT aggregate type that happens to share the
+// moved aggregate's id must stay in the source tenant.
+export async function transferArchivedStreamRows(
+  db: AnyDb,
+  params: TransferArchivedStreamRowsParams,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `UPDATE "kumiko_archived_streams" SET "tenant_id" = $1 ` +
+      `WHERE "tenant_id" = $2 AND "aggregate_type" = $3 AND "aggregate_id" = ANY($4)`,
+    [params.destinationTenantId, params.sourceTenantId, params.aggregateType, params.aggregateIds],
+  );
+}

package/src/engine/__tests__/entity-handlers.test.ts

@@ -110,6 +110,34 @@ describe("defineEntityWriteHandler", () => {
     // @ts-expect-error access is required since fw#2855 — no implicit openToAll.
     expect(() => defineEntityCreateHandler("note", noteEntity)).toThrow();
   });
+
+  test("delete on an entity without softDelete defaults agent.risk to high", () => {
+    const def = defineEntityDeleteHandler("note", noteEntity, adminAccess);
+    expect(resolveAgentExposure(def, "write").risk).toBe("high");
+  });
+
+  test("delete on an entity without softDelete preserves other agent hints while forcing risk high", () => {
+    const def = defineEntityDeleteHandler("note", noteEntity, {
+      access: { roles: ["Admin"] },
+      agent: { expose: false },
+    });
+    expect(def.agent).toEqual({ expose: false, risk: "high" });
+  });
+
+  test("delete on an entity without softDelete throws when agent.risk is explicitly set below high", () => {
+    expect(() =>
+      defineEntityDeleteHandler("note", noteEntity, {
+        access: { roles: ["Admin"] },
+        agent: { risk: "mid" },
+      }),
+    ).toThrow(/agent\.risk must be "high"/);
+  });
+
+  test("delete on a softDelete entity leaves agent hints untouched", () => {
+    const def = defineEntityDeleteHandler("note", noteEntitySoftDelete, adminAccess);
+    expect(def.agent).toBeUndefined();
+    expect(resolveAgentExposure(def, "write").risk).toBe("mid");
+  });
 });
 
 describe("defineEntityQueryHandler", () => {

package/src/engine/__tests__/steps-webhook-send.test.ts

@@ -39,7 +39,7 @@ describe("buildWebhookSendStep", () => {
       method: "PUT",
       headers: { "X-Custom": "val" },
       body: { event: "test" },
-      auth: { kind: "bearer", secretRef: "MY_SECRET" },
+      auth: { kind: "bearer", secret: "MY_SECRET" },
       retry: { times: 5, backoff: "linear" },
       mode: "deferred",
     });
@@ -125,7 +125,7 @@ describe("webhook.send run", () => {
 
   it("passes auth config through when provided", async () => {
     const stepDef = getStep("webhook.send");
-    const auth = { kind: "bearer" as const, secretRef: "WEBHOOK_TOKEN" };
+    const auth = { kind: "bearer" as const, secret: "WEBHOOK_TOKEN" };
 
     await stepDef!.run({ url: "https://hooks.example/secured", mode: "deferred", auth }, mockCtx);
 

package/src/engine/entity-handlers.ts

@@ -16,6 +16,7 @@ import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
 import type {
   AccessRule,
+  AgentHandlerHints,
   DeriveContext,
   EntityDefinition,
   EscapeHatchDeclaration,
@@ -213,6 +214,23 @@ function isInTotalsMatchPair(entity: EntityDefinition, fieldName: string): boole
   );
 }
 
+// delete on an entity without softDelete hard-purges the row — the agent
+// risk gate only protects it if this handler resolves to "high".
+function resolveEntityWriteAgentHints(
+  name: string,
+  verb: (typeof WRITE_VERBS)[number],
+  entity: EntityDefinition,
+  agent: AgentHandlerHints | undefined,
+): AgentHandlerHints | undefined {
+  if (verb !== "delete" || entity.softDelete) return agent;
+  if (agent?.risk !== undefined && agent.risk !== "high") {
+    throw new Error(
+      `"${name}": delete on an entity without softDelete is irreversible — agent.risk must be "high" (got "${agent.risk}").`,
+    );
+  }
+  return { ...agent, risk: "high" };
+}
+
 function assertExcludableFields(
   name: string,
   verb: (typeof WRITE_VERBS)[number],
@@ -253,6 +271,7 @@ export function defineEntityWriteHandler(
       `"${name}": restore is only valid for entities declared with softDelete: true.`,
     );
   }
+  const agentHints = resolveEntityWriteAgentHints(name, verb, entity, options.agent);
   const excludedFields = options.excludeFields ?? [];
   assertExcludableFields(name, verb, entity, excludedFields);
 
@@ -378,7 +397,7 @@ export function defineEntityWriteHandler(
     handler,
     access: options.access,
     ...(options.description !== undefined && { description: options.description }),
-    ...(options.agent !== undefined && { agent: options.agent }),
+    ...(agentHints !== undefined && { agent: agentHints }),
   };
 }
 

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/alias-reexport.ts

@@ -0,0 +1 @@
+export { ORIGIN_VALUE as ALIASED } from "./origin";

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/cycle-a.ts

@@ -0,0 +1 @@
+export * from "./cycle-b";

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/cycle-b.ts

@@ -0,0 +1 @@
+export * from "./cycle-a";

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/entry.ts

@@ -0,0 +1,3 @@
+import { ALIASED as RENAMED } from "./star-barrel";
+
+export const marker: string = RENAMED;