@company-semantics/contracts 78.0.0 → 79.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "78.0.0",
+  "version": "79.0.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 = '7fba2cafe8fa' as const;
-export const SPEC_HASH_FULL = '7fba2cafe8fac0d1d504b68950dc7991091381a49522af2660bc8bcb3b2a865a' as const;
+export const SPEC_HASH = '554ba5a13882' as const;
+export const SPEC_HASH_FULL = '554ba5a138827be4f4959d0a9d0199be36e129c9caacce47370121ffede938bf' as const;

package/src/api/generated.ts

@@ -7470,6 +7470,7 @@ export interface components {
                 title: string;
                 detail: string | null;
                 contextLabel: string;
+                provider: string | null;
                 href: string;
                 createdAt: string;
             }[];
@@ -7491,6 +7492,7 @@ export interface components {
                     title: string;
                     detail: string | null;
                     contextLabel: string;
+                    provider: string | null;
                     href: string;
                     createdAt: string;
                 };
@@ -7500,7 +7502,7 @@ export interface components {
                 notification: {
                     id: string;
                     /** @enum {string} */
-                    kind: "companyMd.access_requested" | "companyMd.access_request_approved" | "companyMd.access_request_denied" | "comment.mention" | "comment.reply" | "chat.mention" | "proactive.org_became_shared" | "proactive.brief_morning" | "proactive.billing_balance_below_half" | "proactive.billing_balance_below_threshold" | "proactive.billing_auto_recharge_succeeded" | "proactive.billing_top_up_credited" | "proactive.billing_monthly_budget_80" | "proactive.billing_monthly_budget_100" | "proactive.billing_user_monthly_limit_reached" | "proactive.billing_byo_key_invalid" | "proactive.billing_provider_price_changed" | "proactive.billing_payment_recovered" | "proactive.billing_balance_exhausted" | "proactive.billing_auto_recharge_failed" | "proactive.billing_payment_past_due" | "proactive.billing_suspended" | "proactive.billing_subscription_canceled" | "proactive.source_sync_docs_updated" | "proactive.source_sync_review_ready";
+                    kind: "companyMd.access_requested" | "companyMd.access_request_approved" | "companyMd.access_request_denied" | "comment.mention" | "comment.reply" | "chat.mention" | "proactive.org_became_shared" | "proactive.brief_morning" | "proactive.billing_balance_below_half" | "proactive.billing_balance_below_threshold" | "proactive.billing_auto_recharge_succeeded" | "proactive.billing_top_up_credited" | "proactive.billing_monthly_budget_80" | "proactive.billing_monthly_budget_100" | "proactive.billing_user_monthly_limit_reached" | "proactive.billing_byo_key_invalid" | "proactive.billing_provider_price_changed" | "proactive.billing_payment_recovered" | "proactive.billing_balance_exhausted" | "proactive.billing_auto_recharge_failed" | "proactive.billing_payment_past_due" | "proactive.billing_suspended" | "proactive.billing_subscription_canceled" | "proactive.source_sync_docs_updated" | "proactive.source_sync_review_ready" | "proactive.org_structure_review_ready";
                     target: {
                         /** @enum {string} */
                         type: "company_md" | "org_unit" | "org" | "execution";
@@ -7510,6 +7512,7 @@ export interface components {
                     title: string;
                     detail: string | null;
                     contextLabel: string;
+                    provider: string | null;
                     href: string | null;
                     createdAt: string;
                     readAt: string | null;

package/src/proactive/README.md

@@ -128,6 +128,12 @@ the three from another.
   candidate set id or the synthesis batch id for `review_ready`. Their inbox
   rows are `proactive.source_sync_*`, distinct from the kind strings. Neither
   sets `emailKind`.
+- **`orgStructure.review_ready` is a `notice`** (the ADR with slug
+  `org-structure-review-ready-is-a-notice`). The first-sync analysis finished
+  and its proposal waits for review. Its counts are scope-gated and nothing is
+  broken, so it gets an unread inbox row (`proactive.org_structure_review_ready`)
+  and no chat or banner. It is triggered by the committed insert of a
+  `validated` proposal, and its occurrence key is the proposal id.
 - **The occurrence vocabulary is closed.** `ProactiveEventId` is branded so a
   raw string cannot stand in for an occurrence; `ProactiveRecipientReason` is a
   closed enum because the recipients table is the frozen audit record of who

package/src/proactive/__tests__/vocabulary.test.ts

@@ -257,6 +257,8 @@ describe("the kind registry", () => {
       // renderer is what resolves the scope-gated count and names at read time.
       "sourceSync.docs_updated": "proactive",
       "sourceSync.review_ready": "proactive",
+      // The org structure row is rendered by `src/proactive/` as well.
+      "orgStructure.review_ready": "proactive",
     };
 
     expect(Object.keys(EXPECTED_INBOX_DOMAIN).sort()).toEqual(
@@ -310,6 +312,22 @@ describe("the kind registry", () => {
     expect(plan.inboxKind).toBe("proactive.source_sync_docs_updated");
   });
 
+  it("orgStructure.review_ready is a notice: an unread inbox row, no banner and no chat", () => {
+    // The analysis counts are scope-gated, so a frozen chat has nothing it may
+    // say, and nothing is broken, so there is no banner (control
+    // docs/proactive-delivery.md). The row carries the attention.
+    const plan = PROACTIVE_EVENT_KINDS["orgStructure.review_ready"];
+
+    expect(plan.class).toBe("notice");
+    expect(CLASS_SURFACES[plan.class].chat).toBe(false);
+    expect(CLASS_SURFACES[plan.class].banner).toBe(false);
+    expect("chatTemplate" in plan).toBe(false);
+    expect("bannerType" in plan).toBe(false);
+    expect("emailKind" in plan).toBe(false);
+    expect(bornRead(CLASS_SURFACES[plan.class], "inbox")).toBe(false);
+    expect(plan.inboxKind).toBe("proactive.org_structure_review_ready");
+  });
+
   it("sourceSync.review_ready is explained: a chat and an inbox row, never a banner", () => {
     // A review is waiting, so the chat explains what it is and what happens if
     // it is left alone — and carries the badge. Nothing is broken and nothing

package/src/proactive/kinds.ts

@@ -282,6 +282,26 @@ export const PROACTIVE_EVENT_KIND_IDS = [
    * silent.
    */
   "sourceSync.review_ready",
+
+  // ===========================================================================
+  // Org structure (ADR-BE-680 deferred it; the first-sync notice)
+  // ===========================================================================
+  /**
+   * The analysis a first BambooHR connect started on its own has finished, and
+   * its proposal is waiting for review. A `notice`, which means an inbox row
+   * and nothing else (control docs/proactive-delivery.md): the analysis counts
+   * are scope-gated, so there is nothing a frozen chat may say, and nothing is
+   * broken or stopped, so there is no banner. A person who launched a run by
+   * hand is already watching it dock in their chat (ADR-APP-298), so only the
+   * connect chain's run announces.
+   *
+   * TRIGGER: the committed insert of a `validated` proposal by that run. A
+   * `blocked` proposal is not a review and announces nothing.
+   *
+   * OCCURRENCE KEY: the proposal id. One proposal announces once, however many
+   * times its job is redelivered.
+   */
+  "orgStructure.review_ready",
 ] as const;
 export type ProactiveEventKind = (typeof PROACTIVE_EVENT_KIND_IDS)[number];
 

package/src/proactive/registry.ts

@@ -253,4 +253,13 @@ export const PROACTIVE_EVENT_KINDS = {
     // later (ADR slug `action-items-are-standing-state-not-notifications`).
     actionItemKind: "sourceSync.proposal_pending",
   },
+  /**
+   * A first-sync org structure review is waiting. A NOTICE: the inbox row is
+   * the whole announcement and arrives unread, and the plan union makes a chat
+   * for it a compile error. Keyed on the proposal id.
+   */
+  "orgStructure.review_ready": {
+    class: "notice",
+    inboxKind: "proactive.org_structure_review_ready",
+  },
 } as const satisfies Record<ProactiveEventKind, ProactiveEventDefinition>;

package/src/user-notifications/README.md

@@ -75,6 +75,9 @@ that renders them alongside action items at the top of `/me/work`.
   candidate-set id; the COUNT of updated documents, and which ones, is resolved
   by the renderer at read time under the reader's authority — which is why it
   belongs in this row and never in the frozen pushed chat.
+- **`proactive.org_structure_review_ready` is the org structure notice's row.**
+  It arrives UNREAD, because a `notice` has no other surface to hold the badge.
+  The renderer links it to the place the review is opened.
 - **This is a mention row, not a chat-unread model.** Being named is a discrete
   fact you come back to; "this chat has new messages" is not modeled here or
   anywhere, and the proactive `unread` flag on a chat summary stays a one-time

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",
       },
@@ -206,3 +232,12 @@ describe("FeedListResponse", () => {
     ).toBe(false);
   });
 });
+
+describe("the org structure inbox row", () => {
+  it("is registered under the proactive renderer, never under its kind's string", () => {
+    expect(USER_NOTIFICATION_KINDS).toContain(
+      "proactive.org_structure_review_ready",
+    );
+    expect(USER_NOTIFICATION_KINDS).not.toContain("orgStructure.review_ready");
+  });
+});

package/src/user-notifications/kinds.ts

@@ -221,6 +221,14 @@ export const USER_NOTIFICATION_KINDS = [
    * `sourceSync.proposal_pending` ACTION ITEM, not this row.
    */
   "proactive.source_sync_review_ready",
+  /**
+   * The org structure analysis a first BambooHR connect started has finished,
+   * and its review is waiting. The durable row of the
+   * `orgStructure.review_ready` proactive kind, a `notice`: no banner and no
+   * pushed chat, so this row IS the attention and arrives UNREAD. It links to
+   * where the review is opened.
+   */
+  "proactive.org_structure_review_ready",
 ] as const;
 
 export type UserNotificationKind = (typeof USER_NOTIFICATION_KINDS)[number];

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.
    *