@company-semantics/contracts 47.0.0 → 47.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "47.0.0",
+  "version": "47.1.1",
   "private": false,
   "repository": {
     "type": "git",

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/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/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,40 @@ 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'`.
+ *
+ * EXPORTED, though nothing consumes it. This package ships `src`, so every
+ * consumer typechecks this file under ITS OWN compiler options — and the
+ * backend sets `noUnusedLocals`, which rejects an unexported type alias that
+ * nothing references. Keeping it private broke `tsc` in a consumer while
+ * passing here, so the export is what makes the assertion portable, not a
+ * widening of the public vocabulary. Do not "tidy" it away.
+ */
+export type RoutingExhaustivenessWitness = Assert<
+  [Exclude<ResourceKey["type"], RoutedType>] extends [never]
+    ? true
+    : Exclude<ResourceKey["type"], RoutedType>
+>;
 
 /**
  * Canonical ResourceKey → query key conversion.
@@ -214,6 +356,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 +384,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "deletionEligibility":
     case "transferOwnership":
     case "companyMdDocs":
+    case "directGrants":
     case "orgTree":
     case "orgLevelConfig":
     case "peopleOrgChart":
@@ -255,6 +399,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 +422,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 +439,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 +497,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;
 }