@cosmicdrift/kumiko-framework 0.280.0 → 0.281.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.280.0",
+  "version": "0.281.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>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.280.0",
+    "@cosmicdrift/kumiko-types": "0.281.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.280.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.281.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,28 @@
 [
+  {
+    "version": "0.281.0",
+    "type": "breaking",
+    "title": "declareEscapeHatch is a new export from @cosmicdrift/kumiko-framework/engine",
+    "migration": "A standalone helper that escalates (`unsafeRaw`, or `queryAs`/`writeAs` with a\nsystem identity) on a `HandlerContext` handed to it by its caller — rather than\nbaselining the Escape-Hatch-Declared Guard finding — declares it at the call\nsite instead: `declareEscapeHatch({ reason: \"...\" })` as the first statement of\nthe helper's body, describing what is escalated and on whose right (the caller's\nhandler still carries its own `escapeHatch` declaration). The reason must be a\nstring literal and not a placeholder (see the guard's generic-reason check) —\nthere is no boot validator behind this form to catch an empty or vague one."
+  },
+  {
+    "version": "0.281.0",
+    "type": "breaking",
+    "title": "withUnsafeRawGrant is no longer exported from @cosmicdrift/kumiko-framework/db",
+    "migration": "A consumer that imported `withUnsafeRawGrant` from `@cosmicdrift/kumiko-framework/db` to grant itself `unsafeRaw` access declares `escapeHatch: { reason: \"<why>\" }` on the relevant registration (handler, hook, or `r.useExtension(...)`) instead, then fetches the runner with `ctx.db.unsafeRaw(\"<same reason>\")`. No blast radius found outside the framework itself: no app repo, kumiko-platform, kumiko-studio, or kumiko-enterprise code used this symbol."
+  },
+  {
+    "version": "0.281.0",
+    "type": "improvement",
+    "title": "Move escape-hatch reporting from pipeline to observability",
+    "detail": "escape-hatch-report.ts now lives in observability/ instead of pipeline/, removing a runtime layering violation where the db layer imported from pipeline; the public API (@cosmicdrift/kumiko-framework/pipeline exports) is unchanged."
+  },
+  {
+    "version": "0.281.0",
+    "type": "improvement",
+    "title": "Unify all framework packages into one version group",
+    "detail": "kumiko-cli, create-kumiko-app, kumiko-guards, and kumiko-repo-manifest join the existing fixed version group; all 15 non-private packages now share one version number."
+  },
   {
     "version": "0.280.0",
     "type": "breaking",

package/src/db/index.ts

@@ -157,5 +157,4 @@ export {
   createTenantDb,
   createUncheckedSystemDb,
   SYSTEM_SCOPE_CHECK_BRAND,
-  withUnsafeRawGrant,
 } from "./tenant-db";

package/src/db/tenant-db.ts

@@ -27,7 +27,7 @@ import {
 import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
 import { AccessDeniedError, InternalError } from "../errors";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
-import { fallbackEscapeHatchReporter } from "../pipeline/escape-hatch-report";
+import { fallbackEscapeHatchReporter } from "../observability/escape-hatch-report";
 import type { DbRunner } from "./connection";
 import { bindTenantDbRunner, tenantDbRunner } from "./tenant-db-runner";
 

package/src/engine/escape-hatch-declaration.ts

@@ -0,0 +1,7 @@
+import type { EscapeHatchDeclaration } from "@cosmicdrift/kumiko-types/handlers";
+
+// Marks a standalone helper that escalates on a HandlerContext handed to it
+// by its caller. The caller's registration carries the escapeHatch that
+// authorizes it; this call makes the escalation visible at the site where it
+// happens, where the guard and a reviewer both see it.
+export function declareEscapeHatch(_declaration: EscapeHatchDeclaration): void {}

package/src/engine/index.ts

@@ -93,6 +93,7 @@ export {
   type RegisterEntityCrudOptions,
   registerEntityCrud,
 } from "./entity-handlers";
+export { declareEscapeHatch } from "./escape-hatch-declaration";
 export type { EmitCtx } from "./event-helpers";
 export { emitEvent, typedPayload } from "./event-helpers";
 export type { KumikoExtensionName } from "./extension-names";

package/src/jobs/job-runner.ts

@@ -27,8 +27,8 @@ import {
   type SerializedTraceContext,
   type Tracer,
 } from "../observability";
+import { createEscapeHatchReporter } from "../observability/escape-hatch-report";
 import { createDistributedLock, type DistributedLock } from "../pipeline/distributed-lock";
-import { createEscapeHatchReporter } from "../pipeline/escape-hatch-report";
 import { RedisKeys } from "../pipeline/redis-keys";
 import { bridgeStub } from "../testing/handler-context";
 

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

@@ -10,8 +10,8 @@ import { executeRawQuery } from "../../db/queries/raw-sql";
 import { createSystemUser, defineFeature } from "../../engine";
 import type { EscapeHatchUseEvent } from "../../engine/types";
 import type { Logger } from "../../logging/types";
+import { ESCAPE_HATCH_USED_SIGNAL } from "../../observability/escape-hatch-report";
 import { createTestUser, setupTestStack, type TestStack } from "../../stack";
-import { ESCAPE_HATCH_USED_SIGNAL } from "../escape-hatch-report";
 
 const globalStoreTable = defineUnmanagedTable({
   tableName: "store_fw2861_escape_hatch_audit_items",

package/src/pipeline/dispatch-shared.ts

@@ -73,6 +73,10 @@ import {
   getFallbackTracer,
   observabilityContext,
 } from "../observability";
+import {
+  createEscapeHatchReporter,
+  type EscapeHatchReportWindow,
+} from "../observability/escape-hatch-report";
 import { buildBucketKey } from "../rate-limit";
 import { createTzContext, isValidIanaTimeZone } from "../time";
 import { INTERACTIVE_SIGN_IN_POLICY, resolveActiveMembershipFn } from "./active-membership";
@@ -85,7 +89,6 @@ import {
   dispatcherSpanAttributes,
   isFailedWriteResult,
 } from "./dispatcher-utils";
-import { createEscapeHatchReporter, type EscapeHatchReportWindow } from "./escape-hatch-report";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
 import { createMemberReaderFn } from "./member-reader";

package/src/pipeline/dispatcher.ts

@@ -20,6 +20,7 @@ import type {
 import type { TenantId } from "../engine/types/identifiers";
 import { reraiseAsKumikoError } from "../errors";
 import { getFallbackMeter, getFallbackTracer, registerStandardMetrics } from "../observability";
+import { createEscapeHatchReportWindow } from "../observability/escape-hatch-report";
 import { INTERACTIVE_SIGN_IN_POLICY, resolveActiveMembershipFn } from "./active-membership";
 import { runBatch, unwrapSingle } from "./dispatch-batch";
 import { executeQuery } from "./dispatch-query";
@@ -27,7 +28,6 @@ import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shar
 import { resolveAuthClaimsFn } from "./dispatch-shared";
 import { executeStream } from "./dispatch-stream";
 import { type HandlerType, resolveType } from "./dispatcher-utils";
-import { createEscapeHatchReportWindow } from "./escape-hatch-report";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
 import { createMemberReaderFn } from "./member-reader";

package/src/pipeline/index.ts

@@ -1,3 +1,11 @@
+export type { EscapeHatchReportWindow } from "../observability/escape-hatch-report";
+export {
+  createEscapeHatchReporter,
+  createEscapeHatchReportWindow,
+  ESCAPE_HATCH_USED_SIGNAL,
+  fallbackEscapeHatchReporter,
+  reportEscapeHatchUse,
+} from "../observability/escape-hatch-report";
 export type { ResolveAuthClaimsArgs } from "./auth-claims-resolver";
 export { resolveAuthClaims } from "./auth-claims-resolver";
 export { createCascadeDeleteHook } from "./cascade-handler";
@@ -7,14 +15,6 @@ export type { DistributedLock } from "./distributed-lock";
 export { createDistributedLock } from "./distributed-lock";
 export type { EntityCache, EntityCacheOptions } from "./entity-cache";
 export { createEntityCache } from "./entity-cache";
-export type { EscapeHatchReportWindow } from "./escape-hatch-report";
-export {
-  createEscapeHatchReporter,
-  createEscapeHatchReportWindow,
-  ESCAPE_HATCH_USED_SIGNAL,
-  fallbackEscapeHatchReporter,
-  reportEscapeHatchUse,
-} from "./escape-hatch-report";
 export type { ConsumerStatus } from "./event-consumer-state";
 export {
   ConsumerStatuses,