@cosmicdrift/kumiko-framework 0.306.0 → 0.308.0

package/package.json

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

package/src/__tests__/anonymous-access.integration.test.ts

@@ -7,7 +7,7 @@
 // Bun.SQL-only setup. KEIN postgres-js, KEIN setupTestStack.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import type { AnonymousAccessConfig } from "../api/auth-middleware";
 import { createEventStoreExecutor } from "../db/event-store-executor";
 import { asRawClient, selectMany } from "../db/query";

package/src/__tests__/error-contract.integration.test.ts

@@ -4,7 +4,7 @@
 // and docs promise. If you change the contract, this is the file that moves.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { createEventStoreExecutor } from "../db/event-store-executor";
 import { asRawClient } from "../db/query";
 import { buildEntityTable } from "../db/table-builder";

package/src/__tests__/field-access.integration.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { buildServer } from "../api/server";
 import { createEventStoreExecutor } from "../db/event-store-executor";
 import { buildEntityTable } from "../db/table-builder";

package/src/__tests__/fixtures/migrate-open-to-all/manual-only.expected.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod";
 
 export const listWidgets = {
   name: "widget:list",

package/src/__tests__/fixtures/migrate-open-to-all/manual-only.input.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod";
 
 export const listWidgets = {
   name: "widget:list",

package/src/__tests__/fixtures/migrate-open-to-all/test-simple.expected.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod";
 
 export const listHandler = {
   name: "widget:list",

package/src/__tests__/fixtures/migrate-open-to-all/test-simple.input.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod";
 
 export const listHandler = {
   name: "widget:list",

package/src/__tests__/full-stack.integration.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { updateRows } from "@cosmicdrift/kumiko-framework/testing";
-import { z } from "zod";
+import * as z from "zod";
 import { createEventStoreExecutor } from "../db/event-store-executor";
 import { selectMany } from "../db/query";
 import { defineFeature, type EntityId, type HandlerContext, type SaveContext } from "../engine";

package/src/__tests__/transition-guard.integration.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { updateRows } from "@cosmicdrift/kumiko-framework/testing";
-import { z } from "zod";
+import * as z from "zod";
 import { createEventStoreExecutor } from "../db/event-store-executor";
 import { buildEntityTable } from "../db/table-builder";
 import {

package/src/api/__tests__/api.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { parseSseFrames } from "@cosmicdrift/kumiko-dispatcher-live";
 import { Hono } from "hono";
-import { z } from "zod";
+import * as z from "zod";
 import {
   createEntity,
   createRegistry,

package/src/api/__tests__/batch.integration.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
-import { z } from "zod";
+import * as z from "zod";
 import type { TableColumns } from "../../db/dialect";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { asRawClient, selectMany } from "../../db/query";

package/src/api/__tests__/body-limit.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
 import { BODY_LIMIT_OPT_OUT_PATHS, Routes } from "../api-constants";
 import { buildServer } from "../server";

package/src/api/__tests__/dispatcher-live.integration.test.ts

@@ -1,7 +1,7 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { createLiveDispatcher } from "@cosmicdrift/kumiko-dispatcher-live";
 import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
-import { z } from "zod";
+import * as z from "zod";
 import { generateToken } from "../../api/tokens";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { asRawClient, selectMany } from "../../db/query";

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

@@ -4,7 +4,7 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { createHmac } from "node:crypto";
-import { z } from "zod";
+import * as z from "zod";
 import { createRegistry, defineFeature, type TenantId } from "../../engine";
 import { RateLimitError } from "../../errors";
 import { setupTestStack, type TestStack, TestUsers } from "../../stack";

package/src/api/__tests__/http-route-rate-limit.integration.test.ts

@@ -5,7 +5,7 @@
 // httpRoute, same client IP, DO hit the limit.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { createEntity, createTextField, defineFeature } from "../../engine";
 import type { TenantId } from "../../engine/types/identifiers";
 import { RateLimitError } from "../../errors";

package/src/api/__tests__/nested-write-ownership.integration.test.ts

@@ -8,7 +8,7 @@
 // setupTestStack + stack.http.write — never createTestDispatcher.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { executeRawQuery } from "../../db/queries/raw-sql";
 import { asRawClient, selectMany } from "../../db/query";

package/src/api/__tests__/nested-write.integration.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { asRawClient, selectMany } from "../../db/query";
 import { buildEntityTable } from "../../db/table-builder";

package/src/api/__tests__/pii-leak-guard.integration.test.ts

@@ -5,7 +5,7 @@
 
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
 import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
-import { z } from "zod";
+import * as z from "zod";
 import { configurePiiSubjectKms, InMemoryKmsAdapter } from "../../crypto";
 import { defineFeature } from "../../engine/define-feature";
 import { defineQueryHandler } from "../../engine/define-handler";

package/src/api/__tests__/redis-sse-broker.integration.test.ts

@@ -127,6 +127,139 @@ describe("createRedisSseBroker", () => {
     expect(invalidatedA).toBe(false);
   });
 
+  test("publishAccessInvalidation with an all-except-session scope spares only the listener whose own sid matches exactly", async () => {
+    const podA = trackedBroker();
+    const podB = trackedBroker();
+    const userId = `user-${generateId()}`;
+    const sidKept = `sid-kept-${generateId()}`;
+    const sidAlreadyRevoked = `sid-already-revoked-${generateId()}`;
+    let invalidatedKept = false;
+    let invalidatedSidless = false;
+    let invalidatedAlreadyRevoked = false;
+
+    podA.subscribeAccessInvalidation(
+      userId,
+      () => {
+        invalidatedKept = true;
+      },
+      { sid: sidKept },
+    );
+    // No sid — mirrors a PAT/bearer stream, always invalidated (fail-closed).
+    podA.subscribeAccessInvalidation(userId, () => {
+      invalidatedSidless = true;
+    });
+    // Not the kept sid — mirrors a session already revoked through an
+    // eventless path (plain logout): the keep-list must still close it.
+    podA.subscribeAccessInvalidation(
+      userId,
+      () => {
+        invalidatedAlreadyRevoked = true;
+      },
+      { sid: sidAlreadyRevoked },
+    );
+
+    await waitFor(() => {
+      podB.publishAccessInvalidation(userId, {
+        kind: "all-except-session",
+        keptSessionId: sidKept,
+      });
+      return invalidatedSidless && invalidatedAlreadyRevoked;
+    });
+    // Asserted only after the control listeners above already fired for the
+    // same publish — proves the pipe delivered the message at all, so a
+    // false here means the sid really was spared, not that delivery is slow.
+    expect(invalidatedKept).toBe(false);
+  });
+
+  test("publishAccessInvalidation with a sessions scope closes only the matching sid, spares an unrelated sid and a PAT listener", async () => {
+    const podA = trackedBroker();
+    const podB = trackedBroker();
+    const userId = `user-${generateId()}`;
+    const sidTarget = `sid-target-${generateId()}`;
+    const sidOther = `sid-other-${generateId()}`;
+    let invalidatedTarget = false;
+    let invalidatedOther = false;
+    let invalidatedPat = false;
+
+    podA.subscribeAccessInvalidation(
+      userId,
+      () => {
+        invalidatedTarget = true;
+      },
+      { sid: sidTarget },
+    );
+    podA.subscribeAccessInvalidation(
+      userId,
+      () => {
+        invalidatedOther = true;
+      },
+      { sid: sidOther },
+    );
+    podA.subscribeAccessInvalidation(
+      userId,
+      () => {
+        invalidatedPat = true;
+      },
+      { patTokenId: `tok-${generateId()}` },
+    );
+
+    await waitFor(() => {
+      podB.publishAccessInvalidation(userId, { kind: "sessions", sessionIds: [sidTarget] });
+      return invalidatedTarget;
+    });
+    expect(invalidatedOther).toBe(false);
+    expect(invalidatedPat).toBe(false);
+  });
+
+  test("a legacy unscoped invalidation message (bare `1`, pre-scoping pod) still invalidates every listener, sid or not", async () => {
+    const podA = trackedBroker();
+    const publisherRaw = new (await import("ioredis")).default(testRedis.redisUrl);
+    const userId = `user-${generateId()}`;
+    let invalidatedWithSid = false;
+
+    podA.subscribeAccessInvalidation(
+      userId,
+      () => {
+        invalidatedWithSid = true;
+      },
+      { sid: `sid-${generateId()}` },
+    );
+
+    try {
+      await waitFor(async () => {
+        await publisherRaw.publish(`kumiko:sse:inval:${userId}`, JSON.stringify(1));
+        return invalidatedWithSid;
+      });
+      expect(invalidatedWithSid).toBe(true);
+    } finally {
+      publisherRaw.disconnect();
+    }
+  });
+
+  test("a malformed sessions-scope wire payload (empty sessionIds, no keptSessionId key) falls back to userwide", async () => {
+    const podA = trackedBroker();
+    const publisherRaw = new (await import("ioredis")).default(testRedis.redisUrl);
+    const userId = `user-${generateId()}`;
+    let invalidated = false;
+
+    podA.subscribeAccessInvalidation(userId, () => {
+      invalidated = true;
+    });
+
+    try {
+      await waitFor(async () => {
+        await publisherRaw.publish(
+          `kumiko:sse:inval:${userId}`,
+          JSON.stringify({ scope: "sessions", sessionIds: [] }),
+        );
+        return invalidated;
+      });
+      expect(invalidated).toBe(true);
+    } finally {
+      publisherRaw.disconnect();
+    }
+  });
+
   test("a malformed message on the channel namespace is dropped, not thrown, and does not kill delivery", async () => {
     const podA = trackedBroker();
     const publisherRaw = new (await import("ioredis")).default(testRedis.redisUrl);

package/src/api/__tests__/request-locale.integration.test.ts

@@ -10,7 +10,7 @@ import {
   setupTestStack,
   type TestStack,
 } from "@cosmicdrift/kumiko-framework/stack";
-import { z } from "zod";
+import * as z from "zod";
 import { LOCALE_HEADER_NAME } from "../api-constants";
 
 const localeProbe = defineFeature("locale-probe", (r) => {

package/src/api/__tests__/server-boot-guards.test.ts

@@ -1,7 +1,7 @@
 // buildServer boot-time guards + httpRoute verb wiring (PUT branch).
 
 import { describe, expect, spyOn, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import {
   createEntity,
   createFileField,

package/src/api/__tests__/server-error-logging.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import { createRegistry, defineFeature } from "../../engine";
 import { RateLimitError, UnprocessableError } from "../../errors";
 import { TestUsers } from "../../stack";

package/src/api/__tests__/sse-broker.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, mock, test } from "bun:test";
-import { createSseBroker, type SseBroker, type SseEvent } from "../sse-broker";
+import {
+  createSseBroker,
+  type SseBroker,
+  type SseEvent,
+  shouldInvalidateListener,
+} from "../sse-broker";
 
 function requireAccessInvalidation(broker: SseBroker) {
   const subscribe = broker.subscribeAccessInvalidation;
@@ -121,4 +126,142 @@ describe("SSE broker", () => {
     const { publish } = requireAccessInvalidation(createSseBroker());
     expect(() => publish("nobody-listening")).not.toThrow();
   });
+
+  test("publishAccessInvalidation with an all-except-session scope spares only the listener whose own sid matches exactly", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const spared = mock();
+    const unrelated = mock();
+
+    subscribe("user-a", spared, { sid: "sid-kept" });
+    subscribe("user-a", unrelated, { sid: "sid-other" });
+    publish("user-a", { kind: "all-except-session", keptSessionId: "sid-kept" });
+
+    expect(spared).not.toHaveBeenCalled();
+    expect(unrelated).toHaveBeenCalledTimes(1);
+  });
+
+  test("all-except-session still closes a listener whose sid was already revoked through an eventless path (keep-list, not a kill-list)", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const alreadyRevoked = mock();
+
+    // Simulates a stream from a session logged out earlier via a path that
+    // never appended session-revoked — the keep-list must not accidentally
+    // exempt it just because its sid isn't the freshly-kept one.
+    subscribe("user-a", alreadyRevoked, { sid: "sid-logged-out-earlier" });
+    publish("user-a", { kind: "all-except-session", keptSessionId: "sid-kept" });
+
+    expect(alreadyRevoked).toHaveBeenCalledTimes(1);
+  });
+
+  test("all-except-session still fires a listener with no sid of its own (fail-closed, e.g. a PAT/bearer stream)", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const sidless = mock();
+
+    subscribe("user-a", sidless);
+    publish("user-a", { kind: "all-except-session", keptSessionId: "sid-kept" });
+
+    expect(sidless).toHaveBeenCalledTimes(1);
+  });
+
+  test("no scope (unscoped) still invalidates every listener, matching pre-scoping behavior", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const first = mock();
+    const second = mock();
+
+    subscribe("user-a", first, { sid: "sid-1" });
+    subscribe("user-a", second, { sid: "sid-2" });
+    publish("user-a");
+
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  test("sessions scope closes only the matching sid, spares an unrelated sid and a PAT listener", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const matching = mock();
+    const otherSid = mock();
+    const patListener = mock();
+
+    subscribe("user-a", matching, { sid: "sid-1" });
+    subscribe("user-a", otherSid, { sid: "sid-2" });
+    subscribe("user-a", patListener, { patTokenId: "tok-1" });
+    publish("user-a", { kind: "sessions", sessionIds: ["sid-1"] });
+
+    expect(matching).toHaveBeenCalledTimes(1);
+    expect(otherSid).not.toHaveBeenCalled();
+    expect(patListener).not.toHaveBeenCalled();
+  });
+
+  test("sessions scope closes a credential-less listener (fail-closed)", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const credentialless = mock();
+
+    subscribe("user-a", credentialless);
+    publish("user-a", { kind: "sessions", sessionIds: ["sid-1"] });
+
+    expect(credentialless).toHaveBeenCalledTimes(1);
+  });
+
+  test("pat-tokens scope closes only the matching tokenId, spares an unrelated PAT and a session listener", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const matching = mock();
+    const otherToken = mock();
+    const sessionListener = mock();
+
+    subscribe("user-a", matching, { patTokenId: "tok-1" });
+    subscribe("user-a", otherToken, { patTokenId: "tok-2" });
+    subscribe("user-a", sessionListener, { sid: "sid-1" });
+    publish("user-a", { kind: "pat-tokens", tokenIds: ["tok-1"] });
+
+    expect(matching).toHaveBeenCalledTimes(1);
+    expect(otherToken).not.toHaveBeenCalled();
+    expect(sessionListener).not.toHaveBeenCalled();
+  });
+
+  test("pat-tokens scope closes a credential-less listener (fail-closed)", () => {
+    const { subscribe, publish } = requireAccessInvalidation(createSseBroker());
+    const credentialless = mock();
+
+    subscribe("user-a", credentialless);
+    publish("user-a", { kind: "pat-tokens", tokenIds: ["tok-1"] });
+
+    expect(credentialless).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("shouldInvalidateListener matrix", () => {
+  const sidListener = { sid: "sid-1" };
+  const patListener = { patTokenId: "tok-1" };
+  const bareListener = {};
+
+  test("user scope always closes", () => {
+    const scope = { kind: "user" as const };
+    expect(shouldInvalidateListener(sidListener, scope)).toBe(true);
+    expect(shouldInvalidateListener(patListener, scope)).toBe(true);
+    expect(shouldInvalidateListener(bareListener, scope)).toBe(true);
+  });
+
+  test("all-except-session spares only the exact kept sid, closes everything else including credential-less", () => {
+    const scope = { kind: "all-except-session" as const, keptSessionId: "sid-1" };
+    expect(shouldInvalidateListener(sidListener, scope)).toBe(false);
+    expect(shouldInvalidateListener({ sid: "sid-2" }, scope)).toBe(true);
+    expect(shouldInvalidateListener(patListener, scope)).toBe(true);
+    expect(shouldInvalidateListener(bareListener, scope)).toBe(true);
+  });
+
+  test("sessions scope closes a matching sid and a credential-less listener, spares everything else", () => {
+    const scope = { kind: "sessions" as const, sessionIds: ["sid-1"] };
+    expect(shouldInvalidateListener(sidListener, scope)).toBe(true);
+    expect(shouldInvalidateListener({ sid: "sid-2" }, scope)).toBe(false);
+    expect(shouldInvalidateListener(patListener, scope)).toBe(false);
+    expect(shouldInvalidateListener(bareListener, scope)).toBe(true);
+  });
+
+  test("pat-tokens scope closes a matching tokenId and a credential-less listener, spares everything else", () => {
+    const scope = { kind: "pat-tokens" as const, tokenIds: ["tok-1"] };
+    expect(shouldInvalidateListener(patListener, scope)).toBe(true);
+    expect(shouldInvalidateListener({ patTokenId: "tok-2" }, scope)).toBe(false);
+    expect(shouldInvalidateListener(sidListener, scope)).toBe(false);
+    expect(shouldInvalidateListener(bareListener, scope)).toBe(true);
+  });
 });

package/src/api/__tests__/stream-escape-hatch.integration.test.ts

@@ -6,7 +6,7 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { createLiveDispatcher } from "@cosmicdrift/kumiko-dispatcher-live";
-import { z } from "zod";
+import * as z from "zod";
 import { generateToken } from "../../api/tokens";
 import { createSystemUser, defineFeature } from "../../engine";
 import type { SessionUser } from "../../engine/types";

package/src/api/auth-routes.ts

@@ -3,7 +3,7 @@ import type { Context } from "hono";
 import { Hono } from "hono";
 import { deleteCookie, setCookie } from "hono/cookie";
 import type Redis from "ioredis";
-import { z } from "zod";
+import * as z from "zod";
 import { buildSessionRoles } from "../engine/membership-roles";
 import { createAnonymousUser, createSystemUser } from "../engine/system-user";
 import {

package/src/api/redis-sse-broker.ts

@@ -1,4 +1,5 @@
 import { createRedisPubSubSignal } from "../redis/pubsub-signal";
+import type { AccessInvalidationScope } from "./sse-broker";
 import { createSseBroker, type SseBroker, type SseEvent } from "./sse-broker";
 
 // Channel namespace for cross-replica fanout (fw#2625). Every pod publishes
@@ -60,6 +61,56 @@ function isSseEvent(value: unknown): value is SseEvent {
   );
 }
 
+// Invalidation payload: `1` means userwide, `{ keptSessionId }` spares that
+// one session (all-except-session), `{ scope: "sessions", sessionIds }` /
+// `{ scope: "pat-tokens", tokenIds }` narrow to those credentials. A newer
+// scope payload NEVER carries a `keptSessionId` key, by construction —
+// that's what makes it safe for an older pod (which only ever reads
+// `keptSessionId`) to treat any of these as userwide instead of silently
+// sparing something it doesn't understand: fail-closed on a mixed rolling
+// deploy. Anything malformed also falls back to userwide.
+function parseInvalidationScope(payload: unknown): AccessInvalidationScope {
+  if (typeof payload !== "object" || payload === null) return { kind: "user" };
+  const record = payload as Record<string, unknown>;
+
+  if ("scope" in record) {
+    const { scope } = record;
+    if (scope === "sessions") {
+      const sessionIds = readNonEmptyStringArray(record["sessionIds"]);
+      if (sessionIds) return { kind: "sessions", sessionIds };
+    }
+    if (scope === "pat-tokens") {
+      const tokenIds = readNonEmptyStringArray(record["tokenIds"]);
+      if (tokenIds) return { kind: "pat-tokens", tokenIds };
+    }
+    return { kind: "user" };
+  }
+
+  if ("keptSessionId" in record) {
+    const { keptSessionId } = record;
+    if (typeof keptSessionId === "string" && keptSessionId.length > 0) {
+      return { kind: "all-except-session", keptSessionId };
+    }
+    return { kind: "user" };
+  }
+
+  return { kind: "user" };
+}
+
+function readNonEmptyStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value) || value.length === 0) return undefined;
+  return value.every((v): v is string => typeof v === "string") ? value : undefined;
+}
+
+// Mirror of parseInvalidationScope's wire shapes. "sessions"/"pat-tokens"
+// deliberately never include a `keptSessionId` key — see the parser comment.
+function encodeInvalidationScope(scope: AccessInvalidationScope | undefined): unknown {
+  if (scope === undefined || scope.kind === "user") return 1;
+  if (scope.kind === "all-except-session") return { keptSessionId: scope.keptSessionId };
+  if (scope.kind === "sessions") return { scope: "sessions", sessionIds: scope.sessionIds };
+  return { scope: "pat-tokens", tokenIds: scope.tokenIds };
+}
+
 // Transport layer around a local `createSseBroker()` — all client/listener
 // state lives in `inner`, this only moves events across the Redis wire via
 // the shared PubSubSignal. `pushToChannel`/`publishAccessInvalidation` never
@@ -89,7 +140,10 @@ export function createRedisSseBroker(opts: RedisSseBrokerOptions): RedisSseBroke
     }
 
     if (channel.startsWith(INVALIDATION_PREFIX)) {
-      inner.publishAccessInvalidation(channel.slice(INVALIDATION_PREFIX.length));
+      inner.publishAccessInvalidation(
+        channel.slice(INVALIDATION_PREFIX.length),
+        parseInvalidationScope(payload),
+      );
     }
   });
 
@@ -108,8 +162,8 @@ export function createRedisSseBroker(opts: RedisSseBrokerOptions): RedisSseBroke
     // stream must close on every replica, not just the one that observed
     // the revocation event. Publishing (rather than calling inner directly,
     // like the in-memory broker does) is what makes that true here.
-    publishAccessInvalidation(userId) {
-      signal.publish(`${INVALIDATION_PREFIX}${userId}`, 1);
+    publishAccessInvalidation(userId, scope) {
+      signal.publish(`${INVALIDATION_PREFIX}${userId}`, encodeInvalidationScope(scope));
     },
 
     close: signal.close,

package/src/api/request-context.ts

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { isPersonalDataGated, type WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
 import { generateId } from "../utils";
 
 // Request-scoped propagation. Populated by the HTTP middleware and by the
@@ -48,6 +49,9 @@ export type RequestContextData = {
   // performance.now() at request entry, so a failing request can report how
   // long it ran. Monotonic — a wall-clock step cannot make it negative.
   readonly startedAt?: number;
+  // 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;
 };
 
 const storage = new AsyncLocalStorage<RequestContextData>();
@@ -87,3 +91,23 @@ export function runWithOrigin<T>(
     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();
+  if (!isPersonalDataGated(origin)) {
+    if (!current?.writeOrigin) return fn();
+    const { writeOrigin: _writeOrigin, ...rest } = current;
+    return requestContext.run(rest, fn);
+  }
+  const requestId = current?.requestId ?? requestContext.generateId();
+  return requestContext.run(
+    {
+      ...current,
+      requestId,
+      correlationId: current?.correlationId ?? requestId,
+      writeOrigin: origin,
+    },
+    fn,
+  );
+}