@company-semantics/contracts 5.0.0 → 6.0.0

package/package.json

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

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

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import {
+  toQueryKey,
+  fromQueryKey,
+  matchesResourceKey,
+  type ResourceKey,
+} from '../resource-keys.js';
+
+const ORG_ID = '11111111-1111-4111-8111-111111111111';
+
+describe('resource-keys: orgUnitOwners (org-scoped)', () => {
+  const key: ResourceKey = { type: 'orgUnitOwners', orgId: ORG_ID };
+
+  it('toQueryKey produces [type, orgId] with no unitId', () => {
+    const qk = toQueryKey(key);
+    expect(qk).toEqual(['orgUnitOwners', ORG_ID]);
+    // org-scoped: exactly two segments, no per-unit identity
+    expect(qk).toHaveLength(2);
+  });
+
+  it('roundtrips through fromQueryKey', () => {
+    const parsed = fromQueryKey(toQueryKey(key));
+    expect(parsed).toEqual(key);
+    expect('unitId' in parsed).toBe(false);
+  });
+
+  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(['orgUnitOwners', other], key)).toBe(false);
+  });
+});
+
+describe('resource-keys: system-scoped internalAdmin* types', () => {
+  const systemTypes = [
+    'internalAdminAiProviders',
+    'internalAdminPrompts',
+    'internalAdminAiRuntimeDefaults',
+  ] as const;
+
+  for (const type of systemTypes) {
+    const key = { type, scope: 'system' } as ResourceKey;
+
+    it(`${type}: toQueryKey produces [type, 'system']`, () => {
+      expect(toQueryKey(key)).toEqual([type, 'system']);
+    });
+
+    it(`${type}: roundtrips through fromQueryKey with scope: 'system'`, () => {
+      const parsed = fromQueryKey(toQueryKey(key));
+      expect(parsed).toEqual(key);
+      expect('orgId' in parsed).toBe(false);
+      expect('userId' in parsed).toBe(false);
+    });
+
+    it(`${type}: matchesResourceKey accepts a matching system key`, () => {
+      expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
+    });
+  }
+
+  it('matchesResourceKey rejects a mismatched system type', () => {
+    const target: ResourceKey = { type: 'internalAdminPrompts', scope: 'system' };
+    expect(matchesResourceKey(['internalAdminAiProviders', 'system'], target)).toBe(false);
+  });
+});

package/src/index.ts

@@ -354,14 +354,11 @@ export {
   AuthorityMechanismSchema,
   AuthorityLocalitySchema,
   AuthorityMutabilitySchema,
-  UnitAuthorityScopeSchema,
-  ALL_UNIT_AUTHORITY_SCOPES,
   OwnerAuthoritySchema,
   OrgUnitOwnerSchema,
   OrgUnitOwnersResponseSchema,
   DelegationSchema,
   CreateDelegationRequestSchema,
-  UpdateDelegationScopesRequestSchema,
   DelegationListResponseSchema,
 } from './org/index'
 export type {
@@ -371,13 +368,11 @@ export type {
   AuthorityMechanism,
   AuthorityLocality,
   AuthorityMutability,
-  UnitAuthorityScope,
   OwnerAuthority,
   OrgUnitOwner,
   OrgUnitOwnersResponse,
   Delegation,
   CreateDelegationRequest,
-  UpdateDelegationScopesRequest,
   DelegationListResponse,
 } from './org/index'
 

package/src/org/index.ts

@@ -277,14 +277,11 @@ export {
   AuthorityMechanismSchema,
   AuthorityLocalitySchema,
   AuthorityMutabilitySchema,
-  UnitAuthorityScopeSchema,
-  ALL_UNIT_AUTHORITY_SCOPES,
   OwnerAuthoritySchema,
   OrgUnitOwnerSchema,
   OrgUnitOwnersResponseSchema,
   DelegationSchema,
   CreateDelegationRequestSchema,
-  UpdateDelegationScopesRequestSchema,
   DelegationListResponseSchema,
 } from './schemas';
 export type {
@@ -294,12 +291,10 @@ export type {
   AuthorityMechanism,
   AuthorityLocality,
   AuthorityMutability,
-  UnitAuthorityScope,
   OwnerAuthority,
   OrgUnitOwner,
   OrgUnitOwnersResponse,
   Delegation,
   CreateDelegationRequest,
-  UpdateDelegationScopesRequest,
   DelegationListResponse,
 } from './schemas';

package/src/org/schemas.ts

@@ -820,24 +820,6 @@ export type AuthorityLocality = z.infer<typeof AuthorityLocalitySchema>;
 export const AuthorityMutabilitySchema = z.enum(['derived', 'user_managed']);
 export type AuthorityMutability = z.infer<typeof AuthorityMutabilitySchema>;
 
-/**
- * Permission scopes a unit-authority grant entitles. A leader (structural or
- * rbac mechanism) implicitly holds all three. A delegate holds the subset
- * recorded on its `org_unit_delegations` row.
- */
-export const UnitAuthorityScopeSchema = z.enum([
-  'doc.edit',
-  'doc.acl',
-  'members.manage',
-]);
-export type UnitAuthorityScope = z.infer<typeof UnitAuthorityScopeSchema>;
-
-export const ALL_UNIT_AUTHORITY_SCOPES: readonly UnitAuthorityScope[] = [
-  'doc.edit',
-  'doc.acl',
-  'members.manage',
-];
-
 export const OwnerAuthoritySchema = z.object({
   mechanism: AuthorityMechanismSchema,
   locality: AuthorityLocalitySchema,
@@ -862,12 +844,6 @@ export const OwnerAuthoritySchema = z.object({
    * the revoke action.
    */
   delegationId: z.string().uuid().optional(),
-  /**
-   * Scopes this authority entitles. Derived mechanisms (structural, rbac) hold
-   * the full set; delegated authorities hold the subset stored on the
-   * delegation row. Non-empty.
-   */
-  scopes: z.array(UnitAuthorityScopeSchema).min(1),
 });
 export type OwnerAuthority = z.infer<typeof OwnerAuthoritySchema>;
 
@@ -910,28 +886,15 @@ export const DelegationSchema = z.object({
   revokedAt: z.string().nullable(),
   status: z.enum(['active', 'revoked']),
   note: z.string().nullable(),
-  scopes: z.array(UnitAuthorityScopeSchema).min(1),
 });
 export type Delegation = z.infer<typeof DelegationSchema>;
 
 export const CreateDelegationRequestSchema = z.object({
   userId: z.string().uuid(),
   note: z.string().max(2000).optional(),
-  /**
-   * Optional. Omit to grant the full leader-equivalent scope set.
-   * Provide a non-empty subset to narrow the delegation (e.g. doc edit only).
-   */
-  scopes: z.array(UnitAuthorityScopeSchema).min(1).optional(),
 });
 export type CreateDelegationRequest = z.infer<typeof CreateDelegationRequestSchema>;
 
-export const UpdateDelegationScopesRequestSchema = z.object({
-  scopes: z.array(UnitAuthorityScopeSchema).min(1),
-});
-export type UpdateDelegationScopesRequest = z.infer<
-  typeof UpdateDelegationScopesRequestSchema
->;
-
 export const DelegationListResponseSchema = z.object({
   delegations: z.array(DelegationSchema),
 });

package/src/resource-keys.ts

@@ -36,8 +36,16 @@ export type ResourceKey =
   | { type: 'orgUnitAncestors'; orgId: string; unitId: string }
   | { type: 'orgUnitMemberships'; orgId: string; unitId: string }
   | { type: 'orgUnitPermissions'; orgId: string; unitId: string }
+  // 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 }
   // 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.
+  // No orgId/userId: these live above any single org. scope is the literal 'system'.
+  | { type: 'internalAdminAiProviders'; scope: 'system' }
+  | { type: 'internalAdminPrompts'; scope: 'system' }
+  | { type: 'internalAdminAiRuntimeDefaults'; scope: 'system' }
   // User-scoped
   | { type: 'dismissedBanners'; userId: string }
   | { type: 'userOrgs'; userId: string }
@@ -64,11 +72,20 @@ const ORG_SCOPED_TYPES = [
   'members', 'departments', 'chats', 'teams', 'integrations', 'invites',
   'auditEvents', 'timeline', 'workspace', 'workspaceDomains', 'authSettings',
   'billing', 'aiUsage', 'deletionEligibility', 'transferOwnership', 'companyMdDocs',
-  'orgTree', 'orgLevelConfig', 'peopleOrgChart',
+  'orgTree', 'orgLevelConfig', 'peopleOrgChart', 'orgUnitOwners',
 ] as const;
 
 const USER_SCOPED_TYPES = ['dismissedBanners', 'userOrgs', 'sessions', 'viewer'] as const;
 
+/**
+ * System-scoped types (ADR-CONTRACTS-052) — tenant-less super-admin resources.
+ * Their query key is [type, 'system']; they carry no orgId or userId.
+ * Intentionally NOT exported — internal to the parser like the other scope arrays.
+ */
+const SYSTEM_SCOPED_TYPES = [
+  'internalAdminAiProviders', 'internalAdminPrompts', 'internalAdminAiRuntimeDefaults',
+] as const;
+
 /**
  * Canonical ResourceKey → query key conversion.
  * This is the ONLY function that constructs query keys — no ad-hoc key
@@ -128,8 +145,15 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case 'orgTree':
     case 'orgLevelConfig':
     case 'peopleOrgChart':
+    case 'orgUnitOwners':
       return [key.type, key.orgId] as const;
 
+    // System-scoped (ADR-CONTRACTS-052) — tenant-less super-admin resources
+    case 'internalAdminAiProviders':
+    case 'internalAdminPrompts':
+    case 'internalAdminAiRuntimeDefaults':
+      return [key.type, key.scope] as const;
+
     default: {
       const _exhaustive: never = key;
       throw new Error(`Unknown resource type: ${JSON.stringify(_exhaustive)}`);
@@ -170,6 +194,11 @@ export function fromQueryKey(queryKey: readonly string[]): ResourceKey {
     return { type, orgId: rest[0], [identityFields[type]]: rest[1] } as ResourceKey;
   }
 
+  // System-scoped types (ADR-CONTRACTS-052) — query key is [type, 'system']
+  if ((SYSTEM_SCOPED_TYPES as readonly string[]).includes(type)) {
+    return { type, scope: 'system' } as ResourceKey;
+  }
+
   // User-scoped types
   if ((USER_SCOPED_TYPES as readonly string[]).includes(type)) {
     return { type, userId: rest[0] } as ResourceKey;
@@ -238,6 +267,7 @@ export function matchesResourceKey(queryKey: readonly unknown[], targetKey: Reso
   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 ('unitId' in parsed && 'unitId' in targetKey && parsed.unitId !== targetKey.unitId) return false;
+  if ('scope' in parsed && 'scope' in targetKey && parsed.scope !== targetKey.scope) return false;
 
   return true;
 }