@cosmicdrift/kumiko-framework 0.307.0 → 0.309.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.307.0",
+  "version": "0.309.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.307.0",
-    "@cosmicdrift/kumiko-types": "0.307.0",
+    "@cosmicdrift/kumiko-http": "0.309.0",
+    "@cosmicdrift/kumiko-types": "0.309.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -208,14 +208,14 @@
     "jose": "^6.2.3",
     "meilisearch": "^0.58.0",
     "pino": "^10.3.1",
-    "postgres": "^3.4.9",
+    "postgres": "npm:@bender0oo0/postgres@3.4.9-kumiko.1",
     "temporal-polyfill": "^0.3.2",
     "ts-morph": "^28.0.0",
     "uuid": "^14.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.307.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.309.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,7 +127,7 @@ describe("createRedisSseBroker", () => {
     expect(invalidatedA).toBe(false);
   });
 
-  test("publishAccessInvalidation with a keptSessionId spares only the listener whose own sid matches exactly", async () => {
+  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()}`;
@@ -142,9 +142,9 @@ describe("createRedisSseBroker", () => {
       () => {
         invalidatedKept = true;
       },
-      sidKept,
+      { sid: sidKept },
     );
-    // No ownSid — mirrors a PAT/bearer stream, always invalidated (fail-closed).
+    // No sid — mirrors a PAT/bearer stream, always invalidated (fail-closed).
     podA.subscribeAccessInvalidation(userId, () => {
       invalidatedSidless = true;
     });
@@ -155,11 +155,14 @@ describe("createRedisSseBroker", () => {
       () => {
         invalidatedAlreadyRevoked = true;
       },
-      sidAlreadyRevoked,
+      { sid: sidAlreadyRevoked },
     );
 
     await waitFor(() => {
-      podB.publishAccessInvalidation(userId, sidKept);
+      podB.publishAccessInvalidation(userId, {
+        kind: "all-except-session",
+        keptSessionId: sidKept,
+      });
       return invalidatedSidless && invalidatedAlreadyRevoked;
     });
     // Asserted only after the control listeners above already fired for the
@@ -168,6 +171,46 @@ describe("createRedisSseBroker", () => {
     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);
@@ -179,7 +222,7 @@ describe("createRedisSseBroker", () => {
       () => {
         invalidatedWithSid = true;
       },
-      `sid-${generateId()}`,
+      { sid: `sid-${generateId()}` },
     );
 
     try {
@@ -193,6 +236,30 @@ describe("createRedisSseBroker", () => {
     }
   });
 
+  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;
@@ -122,52 +127,141 @@ describe("SSE broker", () => {
     expect(() => publish("nobody-listening")).not.toThrow();
   });
 
-  test("publishAccessInvalidation with a keptSessionId spares only the listener whose own sid matches exactly", () => {
+  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-kept");
-    subscribe("user-a", unrelated, "sid-other");
-    publish("user-a", "sid-kept");
+    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("publishAccessInvalidation with a keptSessionId still closes a listener whose sid was already revoked through an eventless path (keep-list, not a kill-list)", () => {
+  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-logged-out-earlier");
-    publish("user-a", "sid-kept");
+    subscribe("user-a", alreadyRevoked, { sid: "sid-logged-out-earlier" });
+    publish("user-a", { kind: "all-except-session", keptSessionId: "sid-kept" });
 
     expect(alreadyRevoked).toHaveBeenCalledTimes(1);
   });
 
-  test("publishAccessInvalidation with a keptSessionId still fires a listener with no sid of its own (fail-closed, e.g. a PAT/bearer stream)", () => {
+  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", "sid-kept");
+    publish("user-a", { kind: "all-except-session", keptSessionId: "sid-kept" });
 
     expect(sidless).toHaveBeenCalledTimes(1);
   });
 
-  test("publishAccessInvalidation with no keptSessionId (unscoped) still invalidates every listener, matching pre-scoping behavior", () => {
+  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-1");
-    subscribe("user-a", second, "sid-2");
+    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,15 +61,54 @@ function isSseEvent(value: unknown): value is SseEvent {
   );
 }
 
-// Invalidation payload: `1` means userwide, `{ keptSessionId }` spares that one
-// session. Anything else falls back to userwide. Older pods never read the
-// payload and invalidate userwide, which keeps a mixed rolling deploy safe.
-function extractInvalidationKeptSessionId(payload: unknown): string | undefined {
-  if (typeof payload !== "object" || payload === null || !("keptSessionId" in payload)) {
-    return undefined;
+// 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" };
   }
-  const { keptSessionId } = payload;
-  return typeof keptSessionId === "string" && keptSessionId.length > 0 ? keptSessionId : undefined;
+
+  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
@@ -102,7 +142,7 @@ export function createRedisSseBroker(opts: RedisSseBrokerOptions): RedisSseBroke
     if (channel.startsWith(INVALIDATION_PREFIX)) {
       inner.publishAccessInvalidation(
         channel.slice(INVALIDATION_PREFIX.length),
-        extractInvalidationKeptSessionId(payload),
+        parseInvalidationScope(payload),
       );
     }
   });
@@ -122,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, keptSessionId) {
-      signal.publish(`${INVALIDATION_PREFIX}${userId}`, keptSessionId ? { keptSessionId } : 1);
+    publishAccessInvalidation(userId, scope) {
+      signal.publish(`${INVALIDATION_PREFIX}${userId}`, encodeInvalidationScope(scope));
     },
 
     close: signal.close,