@company-semantics/contracts 46.0.0 → 47.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "46.0.0",
+  "version": "47.1.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -86,6 +86,7 @@
     "build": "tsc -b --noEmit",
     "typecheck": "NODE_OPTIONS='--max-old-space-size=4096' tsc -b --noEmit",
     "typecheck:ci": "NODE_OPTIONS='--max-old-space-size=4096' tsc -p scripts/ci/tsconfig.json",
+    "lint": "eslint src/ scripts/ tests/ __tests__/ vitest.config.ts",
     "lint:md": "markdownlint-cli2 '**/*.md' '#node_modules' '#.ralph/worktrees' '#.claude/worktrees'",
     "format": "prettier --write src/",
     "format:check": "prettier --check src/",
@@ -137,9 +138,11 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^22.20.1",
     "amphtml-validator": "^1.0.38",
     "culori": "^4.0.2",
+    "eslint": "^10.8.1",
     "husky": "^9.1.7",
     "lint-staged": "^17.3.0",
     "markdownlint-cli2": "^0.23.2",
@@ -147,6 +150,7 @@
     "prettier": "^3.9.6",
     "tsx": "^4.23.1",
     "typescript": "^5.8.3",
+    "typescript-eslint": "^8.66.0",
     "vite": "^8.2.0",
     "vitest": "^4.1.10",
     "yaml": "^2.9.0"
@@ -158,6 +162,8 @@
       "nanoid@<3.3.17": ">=3.3.17",
       "js-yaml@>=4.0.0 <4.3.1": ">=4.3.1 <5.0.0",
       "js-yaml@>=5.0.0 <5.2.2": ">=5.2.2 <6.0.0",
+      "ajv@<6.14.0": ">=6.14.0",
+      "flatted@<3.4.0": ">=3.4.0",
       "picomatch@<4.0.4": ">=4.0.4",
       "esbuild@<0.28.1": ">=0.28.1",
       "linkify-it@<5.0.2": ">=5.0.2",

package/src/__tests__/resource-keys.test.ts

@@ -60,6 +60,65 @@ describe("resource-keys: orgUnitOpenRoles (per-unit identity)", () => {
   });
 });
 
+describe("resource-keys: directGrants (org-scoped)", () => {
+  const key: ResourceKey = { type: "directGrants", orgId: ORG_ID };
+
+  it("toQueryKey produces [type, orgId]", () => {
+    const qk = toQueryKey(key);
+    expect(qk).toEqual(["directGrants", ORG_ID]);
+    expect(qk).toHaveLength(2);
+  });
+
+  it("roundtrips through fromQueryKey", () => {
+    expect(fromQueryKey(toQueryKey(key))).toEqual(key);
+  });
+
+  it("matchesResourceKey is org-scoped: rejects a different orgId", () => {
+    const other = "22222222-2222-4222-8222-222222222222";
+    expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
+    expect(matchesResourceKey(["directGrants", other], key)).toBe(false);
+  });
+});
+
+describe("resource-keys: orgUnitMyAuthority (per-unit identity)", () => {
+  const UNIT_ID = "33333333-3333-4333-8333-333333333333";
+  const key: ResourceKey = {
+    type: "orgUnitMyAuthority",
+    orgId: ORG_ID,
+    unitId: UNIT_ID,
+  };
+
+  it("toQueryKey produces [type, orgId, unitId]", () => {
+    const qk = toQueryKey(key);
+    expect(qk).toEqual(["orgUnitMyAuthority", ORG_ID, UNIT_ID]);
+    expect(qk).toHaveLength(3);
+  });
+
+  it("roundtrips through fromQueryKey", () => {
+    expect(fromQueryKey(toQueryKey(key))).toEqual(key);
+  });
+
+  it("matchesResourceKey is unitId-scoped: rejects a different unit", () => {
+    const otherUnit = "44444444-4444-4444-8444-444444444444";
+    expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
+    expect(
+      matchesResourceKey(["orgUnitMyAuthority", ORG_ID, otherUnit], key),
+    ).toBe(false);
+  });
+
+  it("does not collide with orgUnitPermissions on the same unit", () => {
+    const permissions: ResourceKey = {
+      type: "orgUnitPermissions",
+      orgId: ORG_ID,
+      unitId: UNIT_ID,
+    };
+    // Same subject, different resource: an invalidation of one must not sweep
+    // the other, or the split that motivated registering this key is inert.
+    expect(matchesResourceKey(toQueryKey(permissions), key)).toBe(false);
+    expect(matchesResourceKey(toQueryKey(key), permissions)).toBe(false);
+  });
+});
+
 describe("resource-keys: system-scoped internalAdmin* types", () => {
   const systemTypes = [
     "internalAdminAiProviders",
@@ -67,6 +126,7 @@ describe("resource-keys: system-scoped internalAdmin* types", () => {
     "internalAdminAiRuntimeDefaults",
     "factoryFloor",
     "factorySnapshot",
+    "factoryKpis",
   ] as const;
 
   for (const type of systemTypes) {

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '9421bda67789' as const;
-export const SPEC_HASH_FULL = '9421bda67789792a5303137aaeb2f7f886cb490e8db9bee11e03f2de13f94806' as const;
+export const SPEC_HASH = '018976cde74a' as const;
+export const SPEC_HASH_FULL = '018976cde74aa4a20c06c5fb333963bf58199fba93d623cd89cf2a360d95eceb' as const;

package/src/api/generated.ts

@@ -4840,6 +4840,7 @@ export interface components {
             canEdit: boolean;
             canUploadContext?: boolean;
             canManageAcl?: boolean;
+            canComment: boolean;
             canChangeVisibility?: boolean;
             inheritsFromId: string | null;
             inheritsFrom: string | null;

package/src/api/http/routes/ai-chat.ts

@@ -14,7 +14,6 @@ import { buildCapabilityGraph } from "../../../mcp/capability-graph";
 import type {
   MCPToolDescriptor,
   ToolDiscoveryResponse,
-  CapabilityGraph,
 } from "../../../mcp/index";
 
 /**

package/src/comments/README.md

@@ -55,8 +55,9 @@ arbitrate — see the first invariant.
 - **Mention identity renders from the mention row, never from the body
   characters under the range.** A stale or forged range can only
   mis-**highlight**; it can never misattribute a mention to the wrong person.
-  Offsets are nullable (and null on every row today, pending the offset
-  columns) — treat null as "highlight nothing", not as an error.
+  Offsets are nullable — treat null as "highlight nothing", not as an error.
+  Mentions written since ADR-BE-522 carry a real range; older rows carry null
+  permanently, since recovering one would mean searching the body for a name.
 - **These shapes are MIRRORED from the backend route boundary, not authored
   here.** Every bound matches
   `company-semantics-backend/src/api/http/routes/comments/comments.schemas.ts`,

package/src/comments/__tests__/schemas.test.ts

@@ -147,8 +147,9 @@ describe("CommentSchema and the redaction invariant", () => {
 
 describe("CommentMentionSchema offsets", () => {
   it("parses a mention whose range is null", () => {
-    // Null on every row today — `comment_mentions` has no offset columns yet.
-    // A client must render these as "highlight nothing", so they must parse.
+    // The state of every mention written before ADR-BE-522, permanently: the
+    // ranges were never stored and cannot be recovered. A client must render
+    // these as "highlight nothing", so they must parse.
     expect(
       CommentMentionSchema.safeParse(
         makeMention({ startOffset: null, endOffset: null }),

package/src/comments/schemas.ts

@@ -75,12 +75,13 @@ export type CommentSubjectType = z.infer<typeof CommentSubjectTypeSchema>;
  * RANGE. A stale or forged range can therefore only mis-HIGHLIGHT; it can never
  * misattribute a mention to the wrong person.
  *
- * `startOffset`/`endOffset` are NULLABLE, and null on every row today:
- * `comment_mentions` has no offset columns yet, so the ranges the server
- * validates in memory have nowhere to persist. The fields are carried in the
- * TARGET shape so a client is written against the final contract once — treat
- * null as "this mention is in the body somewhere, highlight nothing", not as an
- * error.
+ * `startOffset`/`endOffset` are NULLABLE, and null means "this mention is in
+ * the body somewhere, highlight nothing" — NEVER an error. Every mention
+ * written since ADR-BE-522 carries a real range; rows written before it have
+ * none and never will, because the only way to invent one is to search the body
+ * for a display name, which is the body-as-identity inversion this contract
+ * exists to prevent. A client therefore has to render both, and the two coexist
+ * with no version check on either side.
  *
  * `displayName` is resolved AT READ TIME from the current user record and is
  * never stored on the mention row: a rename re-renders with no backfill, and an

package/src/content/schemas.ts

@@ -173,6 +173,29 @@ export const CompanyMdDocResponseSchema = z.object({
    * outside the single-doc read.
    */
   canManageAcl: z.boolean().optional(),
+  /**
+   * CONVERSATION capability signal (ADR-CONTRACTS-118 / ADR-BE-520): whether the
+   * requesting actor holds `CompanyMd.CanComment` (the `commenter` band and up)
+   * on this doc — the SAME binding `assertCanCommentSubject` enforces on every
+   * comment write AND, since ADR-BE-520, `assertCanReadSubject` enforces on the
+   * thread read. The app mounts or withholds the ENTIRE comment surface on it —
+   * the rail, the toolbar control, the open-thread badge, the preview
+   * highlights, the gutter marks and the thread fetch itself — not merely a
+   * create affordance: a document's conversation sits inside that document's
+   * confidentiality envelope rather than forming an annotation layer over it
+   * (ADR-APP-122). Signal only; admittance and enforcement are unchanged.
+   *
+   * REQUIRED, unlike the three signals above it, and the departure is
+   * deliberate. Those are optional for back-compat with doc shapes returned
+   * outside the single-doc read; this one gates a confidentiality surface, where
+   * an absent value means "unknown" rather than "false" and any client-invented
+   * default is a guess. Making it required is what lets the app delete the
+   * `canComment ?? canEdit` shadow-field fallback outright instead of carrying a
+   * second, weaker answer beside the server's. Pre-launch there is no
+   * back-compat consumer to protect, so the field is required and the package
+   * takes the major bump.
+   */
+  canComment: z.boolean(),
   /**
    * GOVERNANCE capability signal (ADR-BE-435): whether the requesting actor holds
    * `CompanyMd.CanChangeVisibility` (owner OR the `org.manage_content_sharing`

package/src/identity/__tests__/avatar.test.ts

@@ -50,7 +50,7 @@ describe("resolveAvatar", () => {
   });
 
   it("returns initials source when no avatarUrl", () => {
-    const result = resolveAvatar({ fullName: "Ian Heidt" } as any);
+    const result = resolveAvatar({ fullName: "Ian Heidt" });
     expect(result.source).toBe("initials");
     expect(result.initials).toBe("IH");
     expect(result.url).toBeUndefined();

package/src/message-parts/__tests__/wire.test.ts

@@ -1,26 +1,35 @@
 import { describe, it, expect } from "vitest";
 import { WireSurfaceBuilder } from "../wire.js";
+import type { MCPToolDescriptor } from "../../mcp/index.js";
 import type { ExecutionResultData } from "../execution.js";
 import type { UndoResultData } from "../execution.js";
 
+// Deliberately partial fixtures: toolList is a pure wrapper that passes `tools`
+// straight through, so these assert the wrapping, not descriptor validity. Cast
+// through `unknown` rather than `any` — the narrowing is intentional and stated,
+// not an absence of typing.
+const partialTools = (
+  tools: ReadonlyArray<Record<string, unknown>>,
+): MCPToolDescriptor[] => tools as unknown as MCPToolDescriptor[];
+
 describe("WireSurfaceBuilder.toolList", () => {
   it("returns data part with type data-tool-list", () => {
-    const tools = [
+    const tools = partialTools([
       { name: "search", description: "Search tool", inputSchema: {} },
-    ] as any;
+    ]);
     const result = WireSurfaceBuilder.toolList(tools);
     expect(result.type).toBe("data-tool-list");
   });
 
   it("data.tools matches input array exactly", () => {
-    const tools = [
+    const tools = partialTools([
       { name: "search", description: "Search tool", inputSchema: {} },
       {
         name: "fetch",
         description: "Fetch tool",
         inputSchema: { type: "object" },
       },
-    ] as any;
+    ]);
     const result = WireSurfaceBuilder.toolList(tools);
     expect(result.data.tools).toEqual(tools);
   });

package/src/permissions/access-levels.ts

@@ -9,7 +9,11 @@
  * levels are materialized into `effective_acl_grants`, and ADR-CTRL-086 for
  * the aggregation rule (most-permissive across sources).
  *
- * The commenter level is currently a stub — see ADR-CTRL-087.
+ * The commenter level is NO LONGER a stub. ADR-CTRL-087 held the placeholder
+ * open; ADR-BE-512 discharged it by giving the band a real domain (polymorphic
+ * comment threads bound to `CompanyMd.CanComment`), and ADR-BE-520 made that
+ * binding gate thread reads as well as writes. See also ADR-CONTRACTS-118 for
+ * the `canComment` capability signal the doc read publishes.
  *
  * `meta` is the metadata-only tier used for org-admin lifecycle access
  * (ADR-BE-245). It is materialized/derived only — never an explicit

package/src/permissions/access-request.ts

@@ -46,6 +46,10 @@ export const ACCESS_REQUEST_MESSAGE_MAX_LENGTH = 280;
  * is rendered as text, never as markup, so this is about what may be STORED,
  * not about escaping at render time.
  */
+// The control characters ARE the subject of this pattern — it exists to reject
+// them. no-control-regex flags them as probable typos, which is the opposite of
+// the intent documented above.
+// eslint-disable-next-line no-control-regex
 const PLAIN_TEXT = /^[^\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]*$/;
 
 /** POST body to create an access request. */

package/src/resource-keys.ts

@@ -58,6 +58,9 @@ export type ResourceKey =
   | { type: "deletionEligibility"; orgId: string }
   | { type: "transferOwnership"; orgId: string }
   | { type: "companyMdDocs"; orgId: string }
+  // Directly-granted (non-inherited) ACL rows for the org, read by the admin
+  // grants surface (ADR-CONTRACTS-119).
+  | { type: "directGrants"; orgId: string }
   // OrgUnit canonical model (ADR-BE-120) — Phase 2 Wave 4
   | { type: "orgTree"; orgId: string }
   | { type: "orgLevelConfig"; orgId: string }
@@ -74,6 +77,12 @@ export type ResourceKey =
   // Org-unit owners list (ADR-CONTRACTS-052) — owners are an org-wide
   // projection, not a per-unit collection, so unitId is intentionally excluded.
   | { type: "orgUnitOwners"; orgId: string }
+  // THIS VIEWER'S authority over one unit (ADR-CONTRACTS-119) — what the viewer
+  // may do here, not what the unit's permission rows say. Deliberately distinct
+  // from `orgUnitPermissions`: same subject, different resource and different
+  // invalidation trigger (a membership change alters the viewer's authority
+  // without touching the unit's rows), the `actionItems`/`feed` split above.
+  | { type: "orgUnitMyAuthority"; orgId: string; unitId: string }
   // People reporting (ADR-BE-166) — drives the settings Org chart drill-down
   | { type: "peopleOrgChart"; orgId: string }
   // System-scoped (ADR-CONTRACTS-052) — tenant-less super-admin resources.
@@ -85,6 +94,11 @@ export type ResourceKey =
   // dashboard reads over Global-infra factory tables; tenant-less, scope 'system'.
   | { type: "factoryFloor"; scope: "system" }
   | { type: "factorySnapshot"; scope: "system" }
+  // The KPI rollup over the same factory tables (ADR-CONTRACTS-119). Registered
+  // late: the app shipped it as a double-cast key literal, and because
+  // `useResource` disables a query whose `toQueryKey` throws, the panel it backs
+  // never fetched at all. An unregistered key is not a stale read, it is no read.
+  | { type: "factoryKpis"; scope: "system" }
   // Everything awaiting the viewer's decision, across every domain
   // (ADR-CONT-104). ORG-scoped, not user-scoped, even though the content is
   // per-viewer: the bucket differs per org, so a user-keyed entry would serve
@@ -128,7 +142,101 @@ export function resolveScope(context: {
   return { orgId: context.impersonatedOrgId ?? context.orgId };
 }
 
-/** All ResourceKey type literals for exhaustive checking. */
+/*
+ * ---------------------------------------------------------------------------
+ * fromQueryKey's routing tables, and the drift detector over them.
+ * ---------------------------------------------------------------------------
+ *
+ * `toQueryKey` has always been safe: its switch is exhaustive and its `never`
+ * guard makes a new union member a compile error. `fromQueryKey` was not. Its
+ * five lookup tables are hand-maintained, and a member missing from all of them
+ * fell through to a RUNTIME `throw` — which `matchesResourceKey` catches and
+ * turns into "matches nothing", and which `useResource` turns into a query that
+ * never fetches. Silent in both directions (ADR-CONTRACTS-119).
+ *
+ * Two mechanisms, and BOTH are needed:
+ *
+ *   `satisfies` on each table catches a WRONG entry — a typo, or a literal
+ *   parked under the wrong scope. It cannot catch an entry that is simply
+ *   absent, because an array is free to be a subset of its element type.
+ *
+ *   `_EveryResourceKeyIsRouted` below catches the ABSENT entry, which is the
+ *   failure that actually shipped. It is the half that closes the hole.
+ */
+
+/**
+ * The identity segments a member carries — every field that is neither the type
+ * tag nor a scope discriminator. `member` → `"memberId"`; `commentThreads` →
+ * `"subjectType" | "subjectId"`; a scope-only key → `never`.
+ */
+type IdentityFieldsOf<T extends ResourceKey["type"]> = Exclude<
+  keyof Extract<ResourceKey, { type: T }>,
+  "type" | "orgId" | "userId" | "scope"
+>;
+
+/**
+ * Type literals whose whole shape is the tag plus one scope discriminator —
+ * i.e. the members that belong in a scope ARRAY rather than an identity MAP.
+ * Distributes over the union (`K` is a naked type parameter).
+ */
+type ScopeOnlyType<K = ResourceKey> = K extends {
+  type: infer T extends ResourceKey["type"];
+}
+  ? [IdentityFieldsOf<T>] extends [never]
+    ? T
+    : never
+  : never;
+
+type OrgScopedType = Extract<
+  ScopeOnlyType,
+  Extract<ResourceKey, { orgId: string }>["type"]
+>;
+type UserScopedType = Extract<
+  ScopeOnlyType,
+  Extract<ResourceKey, { userId: string }>["type"]
+>;
+type SystemScopedType = Extract<
+  ScopeOnlyType,
+  Extract<ResourceKey, { scope: "system" }>["type"]
+>;
+
+/**
+ * Identities with a single extra segment. The `satisfies` checks the FIELD NAME
+ * against that member's own keys, so renaming `memberId` in the union — or
+ * pointing a key at a field it does not have — fails to compile here.
+ */
+const IDENTITY_FIELDS = {
+  member: "memberId",
+  team: "teamId",
+  department: "departmentId",
+  chat: "chatId",
+  companyMdDoc: "slug",
+  companyMdContextBank: "slug",
+  companyMdAccessRequests: "docId",
+  orgUnit: "unitId",
+  orgUnitChildren: "unitId",
+  orgUnitAncestors: "unitId",
+  orgUnitMemberships: "unitId",
+  orgUnitPermissions: "unitId",
+  orgUnitOpenRoles: "unitId",
+  orgUnitMyAuthority: "unitId",
+} as const satisfies { [T in ResourceKey["type"]]?: IdentityFieldsOf<T> };
+
+/**
+ * Identities with a COMPOSITE (multi-segment) identity. Checked before
+ * {@link IDENTITY_FIELDS}, which hard-asserts a two-element `rest` and would
+ * otherwise reject these.
+ *
+ * A map of its own rather than widening `IDENTITY_FIELDS` to `string | string[]`:
+ * the single-segment case is every other key in the union, and making it pay for
+ * this one would put a branch in the hot path for no reader's benefit.
+ */
+const COMPOSITE_IDENTITY_FIELDS = {
+  commentThreads: ["subjectType", "subjectId"],
+} as const satisfies {
+  [T in ResourceKey["type"]]?: readonly IdentityFieldsOf<T>[];
+};
+
 const ORG_SCOPED_TYPES = [
   "members",
   "departments",
@@ -146,13 +254,14 @@ const ORG_SCOPED_TYPES = [
   "deletionEligibility",
   "transferOwnership",
   "companyMdDocs",
+  "directGrants",
   "orgTree",
   "orgLevelConfig",
   "peopleOrgChart",
   "orgUnitOwners",
   "actionItems",
   "feed",
-] as const;
+] as const satisfies readonly OrgScopedType[];
 
 const USER_SCOPED_TYPES = [
   "dismissedBanners",
@@ -160,7 +269,7 @@ const USER_SCOPED_TYPES = [
   "sessions",
   "userMd",
   "viewer",
-] as const;
+] as const satisfies readonly UserScopedType[];
 
 /**
  * System-scoped types (ADR-CONTRACTS-052) — tenant-less super-admin resources.
@@ -173,7 +282,34 @@ const SYSTEM_SCOPED_TYPES = [
   "internalAdminAiRuntimeDefaults",
   "factoryFloor",
   "factorySnapshot",
-] as const;
+  "factoryKpis",
+] as const satisfies readonly SystemScopedType[];
+
+/** Every literal `fromQueryKey` can route, across all five tables. */
+type RoutedType =
+  | keyof typeof IDENTITY_FIELDS
+  | keyof typeof COMPOSITE_IDENTITY_FIELDS
+  | (typeof ORG_SCOPED_TYPES)[number]
+  | (typeof USER_SCOPED_TYPES)[number]
+  | (typeof SYSTEM_SCOPED_TYPES)[number];
+
+type Assert<T extends true> = T;
+
+/**
+ * THE DRIFT DETECTOR. Register a union member and forget its routing table and
+ * this fails to compile — instead of shipping a key that parses nowhere,
+ * matches nothing, and disables the query that reads it.
+ *
+ * The false branch resolves to the UNROUTED LITERALS rather than to `false`, so
+ * the diagnostic names the culprit:
+ *   `Type '"directGrants"' does not satisfy the constraint 'true'`.
+ * Deliberately unexported: this is an assertion, not vocabulary.
+ */
+type _EveryResourceKeyIsRouted = Assert<
+  [Exclude<ResourceKey["type"], RoutedType>] extends [never]
+    ? true
+    : Exclude<ResourceKey["type"], RoutedType>
+>;
 
 /**
  * Canonical ResourceKey → query key conversion.
@@ -214,6 +350,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "orgUnitMemberships":
     case "orgUnitPermissions":
     case "orgUnitOpenRoles":
+    case "orgUnitMyAuthority":
       return [key.type, key.orgId, key.unitId] as const;
 
     // User-scoped
@@ -241,6 +378,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "deletionEligibility":
     case "transferOwnership":
     case "companyMdDocs":
+    case "directGrants":
     case "orgTree":
     case "orgLevelConfig":
     case "peopleOrgChart":
@@ -255,6 +393,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "internalAdminAiRuntimeDefaults":
     case "factoryFloor":
     case "factorySnapshot":
+    case "factoryKpis":
       return [key.type, key.scope] as const;
 
     default: {
@@ -277,19 +416,9 @@ export function fromQueryKey(queryKey: readonly string[]): ResourceKey {
     );
   }
 
-  // Identities with a COMPOSITE (multi-segment) identity. Checked before the
-  // single-field map below, which hard-asserts a two-element `rest` and would
-  // otherwise reject these.
-  //
-  // A map of its own rather than a widening of `identityFields` to a
-  // `string | string[]`: the single-segment case is every other key in the
-  // union, and making it pay for this one would put a branch in the hot path
-  // for no reader's benefit.
-  const compositeIdentityFields: Record<string, readonly string[]> = {
-    commentThreads: ["subjectType", "subjectId"],
-  };
-
-  const compositeFields = compositeIdentityFields[type];
+  const compositeFields = (
+    COMPOSITE_IDENTITY_FIELDS as Record<string, readonly string[] | undefined>
+  )[type];
   if (compositeFields) {
     // +1 for the orgId that leads every composite key.
     if (rest.length !== compositeFields.length + 1) {
@@ -304,33 +433,21 @@ export function fromQueryKey(queryKey: readonly string[]): ResourceKey {
     return key as ResourceKey;
   }
 
-  // Identities with extra field
-  const identityFields: Record<string, string> = {
-    member: "memberId",
-    team: "teamId",
-    department: "departmentId",
-    chat: "chatId",
-    companyMdDoc: "slug",
-    companyMdContextBank: "slug",
-    companyMdAccessRequests: "docId",
-    orgUnit: "unitId",
-    orgUnitChildren: "unitId",
-    orgUnitAncestors: "unitId",
-    orgUnitMemberships: "unitId",
-    orgUnitPermissions: "unitId",
-    orgUnitOpenRoles: "unitId",
-  };
-
-  if (type in identityFields) {
+  // Identities with a single extra segment.
+  const identityField = (IDENTITY_FIELDS as Record<string, string | undefined>)[
+    type
+  ];
+
+  if (identityField !== undefined) {
     if (rest.length !== 2) {
       throw new Error(
-        `Invalid query key for '${type}': expected [type, orgId, ${identityFields[type]}], got ${JSON.stringify(queryKey)}`,
+        `Invalid query key for '${type}': expected [type, orgId, ${identityField}], got ${JSON.stringify(queryKey)}`,
       );
     }
     return {
       type,
       orgId: rest[0],
-      [identityFields[type]]: rest[1],
+      [identityField]: rest[1],
     } as ResourceKey;
   }
 
@@ -374,76 +491,26 @@ export function matchesResourceKey(
 
   if (parsed.type !== targetKey.type) return false;
 
-  if (
-    "orgId" in parsed &&
-    "orgId" in targetKey &&
-    parsed.orgId !== targetKey.orgId
-  )
-    return false;
-  if (
-    "userId" in parsed &&
-    "userId" in targetKey &&
-    parsed.userId !== targetKey.userId
-  )
-    return false;
-  if (
-    "memberId" in parsed &&
-    "memberId" in targetKey &&
-    parsed.memberId !== targetKey.memberId
-  )
-    return false;
-  if (
-    "teamId" in parsed &&
-    "teamId" in targetKey &&
-    parsed.teamId !== targetKey.teamId
-  )
-    return false;
-  if (
-    "departmentId" in parsed &&
-    "departmentId" in targetKey &&
-    parsed.departmentId !== targetKey.departmentId
-  )
-    return false;
-  if (
-    "chatId" in parsed &&
-    "chatId" in targetKey &&
-    parsed.chatId !== targetKey.chatId
-  )
-    return false;
-  if ("slug" in parsed && "slug" in targetKey && parsed.slug !== targetKey.slug)
-    return false;
-  if (
-    "docId" in parsed &&
-    "docId" in targetKey &&
-    parsed.docId !== targetKey.docId
-  )
-    return false;
-  if (
-    "unitId" in parsed &&
-    "unitId" in targetKey &&
-    parsed.unitId !== targetKey.unitId
-  )
-    return false;
-  // Both halves of a composite identity, or a comment thread list on one
-  // subject would be invalidated by every other subject in the org.
-  if (
-    "subjectType" in parsed &&
-    "subjectType" in targetKey &&
-    parsed.subjectType !== targetKey.subjectType
-  )
-    return false;
-  if (
-    "subjectId" in parsed &&
-    "subjectId" in targetKey &&
-    parsed.subjectId !== targetKey.subjectId
-  )
-    return false;
-  if (
-    "scope" in parsed &&
-    "scope" in targetKey &&
-    parsed.scope !== targetKey.scope
-  )
-    return false;
+  // Field-agnostic on purpose. This was an eleven-branch ladder naming every
+  // scope and identity field by hand — a second, silent mirror of the union's
+  // shape. A member whose identity segment the ladder forgot still matched, so
+  // one subject's invalidation flushed every other subject's cache; that is the
+  // ADR-CONTRACTS-116 `subjectType` defect, and enumerating fields is what made
+  // it possible. Comparing whatever the target actually carries covers a new
+  // identity field by construction (ADR-CONTRACTS-119).
+  //
+  // Same-type comparison only — `parsed.type === targetKey.type` above — so the
+  // two sides are the same union member and a shared field name means the same
+  // thing on both. A field present on one side and absent on the other still
+  // matches, which is what lets a slug-less `{type:'companyMdDocs', orgId}`
+  // sweep its whole type org-wide, exactly as before.
+  const target = targetKey as Record<string, unknown>;
+  const candidate = parsed as Record<string, unknown>;
+  for (const field of Object.keys(target)) {
+    if (field === "type") continue;
+    const other = candidate[field];
+    if (other !== undefined && other !== target[field]) return false;
+  }
 
   return true;
 }

package/src/security/org-secrets.ts

@@ -41,6 +41,9 @@ export const OrgSecretsActionSchema = z.enum([
 ]);
 export type OrgSecretsAction = z.infer<typeof OrgSecretsActionSchema>;
 
+// The brand exists only to be referenced in a type position below; the value
+// binding is never read, which is the whole point of the nominal-typing idiom.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 declare const SecretValueStringBrand: unique symbol;
 
 /**