@company-semantics/contracts 78.1.0 → 79.1.0

package/package.json

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

package/src/action-items/__tests__/vocabulary.test.ts

@@ -31,6 +31,7 @@ function makeItem(over: Partial<Record<string, unknown>> = {}) {
     title: "Maya Chen wants access",
     detail: "Reviewing the cross-team roadmap",
     contextLabel: "Sales.md",
+    provider: null,
     href: "/@acme/md/doc-1?share=1&request=req-1",
     createdAt: "2026-07-27T00:00:00.000Z",
     ...over,
@@ -139,6 +140,15 @@ describe("ActionItemSchema", () => {
     expect(parsed.unitPath).toBeNull();
   });
 
+  it("requires a provider — null when the item is about the product", () => {
+    const { provider: _omitted, ...withoutProvider } = makeItem();
+    expect(ActionItemSchema.safeParse(withoutProvider).success).toBe(false);
+    expect(
+      ActionItemSchema.safeParse(makeItem({ provider: "google_drive" }))
+        .success,
+    ).toBe(true);
+  });
+
   it("rejects a kind outside the vocabulary", () => {
     expect(() =>
       ActionItemSchema.parse(makeItem({ kind: "org.invite" })),

package/src/action-items/schemas.ts

@@ -69,6 +69,16 @@ export const ActionItemSchema = z.object({
   detail: z.string().nullable(),
   /** The thing it is about, as the user names it, e.g. "Sales.md". */
   contextLabel: z.string(),
+  /**
+   * The external system this row is ABOUT, when it is about one — the open
+   * provider id the identity-link vocabulary uses system-wide ('bamboohr',
+   * 'google_drive', 'slack'). A surface shows that system's own mark.
+   *
+   * Set by the producer, because only it knows: an org's structure findings
+   * come from whichever HRIS it connected, which the kind cannot say.
+   * `null` when the row is about the product itself (a doc, a chat, billing).
+   */
+  provider: z.string().min(1).nullable(),
   /**
    * Where to go to RESOLVE it — a RELATIVE app path, e.g.
    * `/@acme/md/{docId}?share=1&request={id}`.

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 = '5fb16e310c8b' as const;
-export const SPEC_HASH_FULL = '5fb16e310c8baf449866b5b84ae859bd3933c7835ba47b6758452fe4dfcceba5' as const;
+export const SPEC_HASH = 'c6eea14298b3' as const;
+export const SPEC_HASH_FULL = 'c6eea14298b3f6282e821b61fac860d7c18fbb8af4b5ecf660bc09665a215d9b' as const;

package/src/api/generated.ts

@@ -4589,6 +4589,30 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/source-sync/settings": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Read whether Source Sync is on for the org
+         * @description The org switch every Source Sync route, job and sweep gates on, and who last changed it and when. Off until an admin turns it on.
+         */
+        get: operations["getSourceSyncSettings"];
+        /**
+         * Switch Source Sync on or off for the org
+         * @description On lets Source Sync search the connected Drive and propose company.md updates for review. Off pauses it: nothing is read or run, and nothing already brought in is deleted. The caller is recorded as the person who changed it.
+         */
+        put: operations["putSourceSyncSettings"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -7470,6 +7494,7 @@ export interface components {
                 title: string;
                 detail: string | null;
                 contextLabel: string;
+                provider: string | null;
                 href: string;
                 createdAt: string;
             }[];
@@ -7491,6 +7516,7 @@ export interface components {
                     title: string;
                     detail: string | null;
                     contextLabel: string;
+                    provider: string | null;
                     href: string;
                     createdAt: string;
                 };
@@ -7510,6 +7536,7 @@ export interface components {
                     title: string;
                     detail: string | null;
                     contextLabel: string;
+                    provider: string | null;
                     href: string | null;
                     createdAt: string;
                     readAt: string | null;
@@ -9293,6 +9320,14 @@ export interface components {
             /** @constant */
             confirm: true;
         };
+        SourceSyncSettingsResponse: {
+            enabled: boolean;
+            changedAt: string | null;
+            changedByLabel: string | null;
+        };
+        SourceSyncPutSettingsRequest: {
+            enabled: boolean;
+        };
         /** @description Server-enforced collaboration size limits, published so clients can pre-check. */
         CollabSyncLimits: {
             maxUpdateBytes: number;
@@ -17245,14 +17280,7 @@ export interface operations {
                     "application/json": components["schemas"]["SourceSyncDiscoveryRunResponse"];
                 };
             };
-            /** @description Source Sync is not enabled */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
-            /** @description The org has no active Google Drive connection (SOURCE_SYNC_DRIVE_NOT_CONNECTED), or a discovery run is already running (SOURCE_DISCOVERY_ALREADY_RUNNING) */
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF), or The org has no active Google Drive connection (SOURCE_SYNC_DRIVE_NOT_CONNECTED), or a discovery run is already running (SOURCE_DISCOVERY_ALREADY_RUNNING) */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -17279,13 +17307,20 @@ export interface operations {
                     "application/json": components["schemas"]["SourceSyncCandidateSetResponse"];
                 };
             };
-            /** @description Source Sync is not enabled, or the org has no draft candidate set */
+            /** @description The org has no draft candidate set */
             404: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF) */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     patchSourceCandidateItem: {
@@ -17327,14 +17362,14 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Source Sync is not enabled, or the set, item or target document is not the org’s */
+            /** @description The set, item or target document is not the org’s */
             404: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description The set is no longer a draft (SOURCE_SYNC_CANDIDATE_SET_NOT_DRAFT), or the item’s scope was already approved (SOURCE_SYNC_CANDIDATE_ITEM_FROZEN) */
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF), or The set is no longer a draft (SOURCE_SYNC_CANDIDATE_SET_NOT_DRAFT), or the item’s scope was already approved (SOURCE_SYNC_CANDIDATE_ITEM_FROZEN) */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -17374,14 +17409,14 @@ export interface operations {
                     "application/json": components["schemas"]["SourceSyncCandidateSetResponse"];
                 };
             };
-            /** @description Source Sync is not enabled, or the set, the file or the target document is not the org’s */
+            /** @description The set, the file or the target document is not the org’s */
             404: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description No active Google Drive connection (SOURCE_SYNC_DRIVE_NOT_CONNECTED), the set is no longer a draft (SOURCE_SYNC_CANDIDATE_SET_NOT_DRAFT), or the file is already on the list for that document (SOURCE_SYNC_CANDIDATE_ALREADY_IN_SET) */
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF), or No active Google Drive connection (SOURCE_SYNC_DRIVE_NOT_CONNECTED), the set is no longer a draft (SOURCE_SYNC_CANDIDATE_SET_NOT_DRAFT), or the file is already on the list for that document (SOURCE_SYNC_CANDIDATE_ALREADY_IN_SET) */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -17425,14 +17460,14 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Source Sync is not enabled, or the set is not the org’s */
+            /** @description The set is not the org’s */
             404: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description Stale revision (SOURCE_SYNC_CANDIDATE_SET_STALE), an unresolved widening (SOURCE_SYNC_TREATMENT_UNRESOLVED), a file with no document (SOURCE_SYNC_TARGET_UNRESOLVED), a scope already approved (SOURCE_SYNC_SCOPE_ALREADY_APPROVED), or a set no longer a draft (SOURCE_SYNC_CANDIDATE_SET_NOT_DRAFT) */
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF), or Stale revision (SOURCE_SYNC_CANDIDATE_SET_STALE), an unresolved widening (SOURCE_SYNC_TREATMENT_UNRESOLVED), a file with no document (SOURCE_SYNC_TARGET_UNRESOLVED), a scope already approved (SOURCE_SYNC_SCOPE_ALREADY_APPROVED), or a set no longer a draft (SOURCE_SYNC_CANDIDATE_SET_NOT_DRAFT) */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -17459,8 +17494,8 @@ export interface operations {
                     "application/json": components["schemas"]["SourceSyncCurrentSynthesisResponse"];
                 };
             };
-            /** @description Source Sync is not enabled */
-            404: {
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF) */
+            409: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -17488,13 +17523,20 @@ export interface operations {
                     "application/json": components["schemas"]["SourceSyncSynthesisResponse"];
                 };
             };
-            /** @description Source Sync is not enabled, or the batch is not the org’s */
+            /** @description The batch is not the org’s */
             404: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF) */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     applySourceSynthesis: {
@@ -17534,14 +17576,14 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Source Sync is not enabled, or the batch or an included change is not the org’s */
+            /** @description The batch or an included change is not the org’s */
             404: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description An included document still has an open question (SOURCE_SYNC_DOC_BLOCKED), or the review or a change is no longer open to apply (SOURCE_SYNC_SYNTHESIS_NOT_OPEN) */
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF), or An included document still has an open question (SOURCE_SYNC_DOC_BLOCKED), or the review or a change is no longer open to apply (SOURCE_SYNC_SYNTHESIS_NOT_OPEN) */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -17568,8 +17610,8 @@ export interface operations {
                     "application/json": components["schemas"]["SourceSyncRulesResponse"];
                 };
             };
-            /** @description Source Sync is not enabled */
-            404: {
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF) */
+            409: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -17606,14 +17648,7 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Source Sync is not enabled */
-            404: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content?: never;
-            };
-            /** @description An active rule already stands for this subject (SOURCE_SYNC_RULE_DUPLICATE); nothing changed */
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF), or An active rule already stands for this subject (SOURCE_SYNC_RULE_DUPLICATE); nothing changed */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -17642,13 +17677,20 @@ export interface operations {
                     "application/json": components["schemas"]["SourceSyncRule"];
                 };
             };
-            /** @description Source Sync is not enabled, or the rule is not the org’s or is already retired */
+            /** @description The rule is not the org’s or is already retired */
             404: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF) */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     listSourceSyncFindings: {
@@ -17676,8 +17718,8 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Source Sync is not enabled */
-            404: {
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF) */
+            409: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -17723,14 +17765,14 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Source Sync is not enabled, or the finding is not the org’s or names no source */
+            /** @description The finding is not the org’s or names no source */
             404: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description The finding already settled on its own (SOURCE_SYNC_FINDING_NOT_OPEN); nothing changed */
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF), or The finding already settled on its own (SOURCE_SYNC_FINDING_NOT_OPEN); nothing changed */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -17764,8 +17806,8 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Source Sync is not enabled */
-            404: {
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF) */
+            409: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -17811,8 +17853,8 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Source Sync is not enabled */
-            404: {
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF) */
+            409: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -17845,8 +17887,8 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Source Sync is not enabled */
-            404: {
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF) */
+            409: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -17890,22 +17932,80 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Source Sync is not enabled */
-            404: {
+            /** @description Source Sync is off for this org (SOURCE_SYNC_OFF), or Workspace-wide access is off or not set up, Drive is not connected or is not a Workspace account, reach is already domain, or Google did not accept the delegation */
+            409: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description Workspace-wide access is off or not set up, Drive is not connected or is not a Workspace account, reach is already domain, or Google did not accept the delegation */
-            409: {
+            /** @description Google could not be reached to verify the delegation */
+            502: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content?: never;
             };
-            /** @description Google could not be reached to verify the delegation */
-            502: {
+        };
+    };
+    getSourceSyncSettings: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The org’s Source Sync switch */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SourceSyncSettingsResponse"];
+                };
+            };
+            /** @description The caller may not manage integrations */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    putSourceSyncSettings: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SourceSyncPutSettingsRequest"];
+            };
+        };
+        responses: {
+            /** @description The switch as it now stands */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SourceSyncSettingsResponse"];
+                };
+            };
+            /** @description Invalid body */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The caller may not manage integrations */
+            403: {
                 headers: {
                     [name: string]: unknown;
                 };

package/src/generated/openapi-routes.ts

@@ -191,6 +191,7 @@ export const openApiRoutes = {
   '/api/source-sync/reach/upgrade': ['POST'],
   '/api/source-sync/rules': ['GET', 'POST'],
   '/api/source-sync/rules/{ruleId}/retire': ['POST'],
+  '/api/source-sync/settings': ['GET', 'PUT'],
   '/api/source-sync/standing-orders': ['GET'],
   '/api/source-sync/standing-orders/{scopeKey}': ['PUT'],
   '/api/source-sync/syntheses/current': ['GET'],

package/src/user-notifications/__tests__/vocabulary.test.ts

@@ -22,6 +22,7 @@ function makeNotification(over: Record<string, unknown> = {}) {
     title: "Dev Patel approved your request",
     detail: null,
     contextLabel: "Q3 OKRs",
+    provider: null,
     href: "/@acme/md/doc-1",
     createdAt: "2026-07-30T12:00:00.000Z",
     readAt: null,
@@ -138,6 +139,30 @@ describe("UserNotificationSchema", () => {
   });
 });
 
+describe("provider — the external system a row is about", () => {
+  it("carries a provider id when the row is about one", () => {
+    expect(
+      UserNotificationSchema.safeParse(
+        makeNotification({ provider: "bamboohr" }),
+      ).success,
+    ).toBe(true);
+  });
+
+  it("is REQUIRED — null says 'about the product', absence says nothing", () => {
+    const { provider: _omitted, ...withoutProvider } = makeNotification();
+    expect(UserNotificationSchema.safeParse(withoutProvider).success).toBe(
+      false,
+    );
+  });
+
+  it("rejects an empty id — a mark nobody can look up", () => {
+    expect(
+      UserNotificationSchema.safeParse(makeNotification({ provider: "" }))
+        .success,
+    ).toBe(false);
+  });
+});
+
 describe("FeedItem discriminates on `row`", () => {
   it("accepts an informational row", () => {
     const parsed = FeedItemSchema.safeParse({
@@ -158,6 +183,7 @@ describe("FeedItem discriminates on `row`", () => {
         title: "Maya Chen wants access",
         detail: null,
         contextLabel: "Q3 OKRs",
+        provider: null,
         href: "/@acme/md/doc-1?share=1&request=req-1",
         createdAt: "2026-07-30T12:00:00.000Z",
       },

package/src/user-notifications/schemas.ts

@@ -49,6 +49,16 @@ export const UserNotificationSchema = z.object({
   detail: z.string().nullable(),
   /** The thing it is about, as the user names it, e.g. "Sales.md". */
   contextLabel: z.string(),
+  /**
+   * The external system this row is ABOUT, when it is about one — the open
+   * provider id the identity-link vocabulary uses system-wide ('bamboohr',
+   * 'google_drive', 'slack'). A surface shows that system's own mark.
+   *
+   * Set by the producer, because only it knows: an org's structure findings
+   * come from whichever HRIS it connected, which the kind cannot say.
+   * `null` when the row is about the product itself (a doc, a chat, billing).
+   */
+  provider: z.string().min(1).nullable(),
   /**
    * Where to go to SEE it — a RELATIVE app path.
    *