@company-semantics/contracts 58.0.0 → 58.2.0

package/src/notifications/__tests__/fixtures.ts

@@ -86,6 +86,15 @@ add("org.invite", "Member", {
   expiresAt: "2026-06-13T00:00:00.000Z",
 });
 
+add("org.invite", "Member + note", {
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "member",
+  acceptUrl: `${APP}/invite/ghi789`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+  message: "We start planning next quarter on Monday — glad you are joining.",
+});
+
 add("org.unit_owner_granted", "Unit owner + message", {
   granterName: "Jordan Lee",
   recipientName: "Sam Chen",

package/src/notifications/__tests__/org-invite.test.ts

@@ -0,0 +1,75 @@
+/**
+ * The invitation's optional note.
+ *
+ * An invite is often the first thing someone ever receives from a workspace, so
+ * the one line of human context on it does real work — and it has to arrive
+ * ATTRIBUTED. A note rendered as product copy reads as boilerplate, which is
+ * the one thing it is not.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { createRenderContext } from "../context";
+import type { ChatUnitItem, NotificationContent } from "../content";
+import { orgInviteDefinition } from "../kinds/org-invite";
+import type { NotificationPayloads } from "../payloads";
+
+const CONTEXT = createRenderContext();
+
+const payload = (
+  over: Partial<NotificationPayloads["org.invite"]> = {},
+): NotificationPayloads["org.invite"] => ({
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "member",
+  acceptUrl: "https://app.companysemantics.ai/invite/abc123",
+  expiresAt: "2026-06-13T00:00:00.000Z",
+  ...over,
+});
+
+function chatItems(content: NotificationContent): ChatUnitItem[] {
+  const elements = content.sections.flatMap((s) => s.elements);
+  const unit = elements.find((e) => e.type === "chatUnit");
+  if (!unit || unit.type !== "chatUnit") throw new Error("no chat unit");
+  return [...unit.items];
+}
+
+describe("org.invite", () => {
+  it("carries the note as the inviter's own words, above the join prompt", () => {
+    const items = chatItems(
+      orgInviteDefinition.compose(
+        payload({ message: "Glad you are joining." }),
+        CONTEXT,
+      ),
+    );
+    expect(items[0]).toEqual({
+      type: "message",
+      role: "user",
+      text: "Glad you are joining.",
+      from: "Alex Rivera",
+    });
+    // The prompt survives the note: the message is WHY someone was invited, the
+    // prompt is what to do about it.
+    expect(items[1]).toMatchObject({
+      role: "assistant",
+      text: "Join to accept the invitation.",
+    });
+  });
+
+  it("renders no message block at all without one", () => {
+    const items = chatItems(orgInviteDefinition.compose(payload(), CONTEXT));
+    expect(items.some((i) => i.type === "message" && i.role === "user")).toBe(
+      false,
+    );
+    expect(items[0]).toMatchObject({ role: "assistant" });
+  });
+
+  it("keeps the call to action last either way", () => {
+    for (const message of [undefined, "Welcome."]) {
+      const items = chatItems(
+        orgInviteDefinition.compose(payload({ message }), CONTEXT),
+      );
+      expect(items[items.length - 1]).toMatchObject({ type: "callToAction" });
+    }
+  });
+});

package/src/notifications/__tests__/render-snapshot.test.ts

@@ -92,6 +92,14 @@ add("org.invite", "Member", {
   acceptUrl: `${APP}/invite/def456`,
   expiresAt: "2026-06-13T00:00:00.000Z",
 });
+add("org.invite", "Member + note", {
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "member",
+  acceptUrl: `${APP}/invite/ghi789`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+  message: "We start planning next quarter on Monday — glad you are joining.",
+});
 
 add("org.unit_owner_granted", "Unit owner + message", {
   granterName: "Jordan Lee",

package/src/notifications/kinds/org-invite.ts

@@ -7,6 +7,7 @@
  * nothing left to catch. See ADR-CONTRACTS-085.
  */
 
+import type { ChatUnitItem } from "../content";
 import type { NotificationDefinition } from "../definition";
 
 import { formatExpiry, NOTICE, titleCase } from "../text";
@@ -14,7 +15,31 @@ import { formatExpiry, NOTICE, titleCase } from "../text";
 export const orgInviteDefinition: NotificationDefinition<"org.invite"> = {
   kind: "org.invite",
   compose: (payload, context) => {
-    const { inviterName, orgName, role, acceptUrl, expiresAt } = payload;
+    const { inviterName, orgName, role, acceptUrl, expiresAt, message } =
+      payload;
+
+    // The inviter's own words come FIRST and keep their name on them, above the
+    // prompt to join — a note attributed to nobody reads as product copy, which
+    // is the one thing it is not. The join prompt stays either way: the message
+    // is why this person was invited, the prompt is what to do about it.
+    const items: ChatUnitItem[] = [
+      ...(message
+        ? [
+            {
+              type: "message" as const,
+              role: "user" as const,
+              text: message,
+              from: inviterName,
+            },
+          ]
+        : []),
+      {
+        type: "message",
+        role: "assistant",
+        text: "Join to accept the invitation.",
+      },
+      { type: "callToAction", label: "JOIN", href: acceptUrl },
+    ];
 
     return {
       metadata: {
@@ -26,17 +51,7 @@ export const orgInviteDefinition: NotificationDefinition<"org.invite"> = {
           elements: [
             { type: "greeting" },
             { type: "body", text: `${orgName} uses Company Semantics.` },
-            {
-              type: "chatUnit",
-              items: [
-                {
-                  type: "message",
-                  role: "assistant",
-                  text: "Join to accept the invitation.",
-                },
-                { type: "callToAction", label: "JOIN", href: acceptUrl },
-              ],
-            },
+            { type: "chatUnit", items },
             {
               type: "keyValueTable",
               rows: [

package/src/notifications/payloads.ts

@@ -51,6 +51,13 @@ export interface NotificationPayloads {
     acceptUrl: string;
     /** ISO timestamp when the invitation expires. Rendered as "Expires: Jun 13, 2026". */
     expiresAt: string;
+    /**
+     * Optional note from the inviter, shown above the join prompt and attributed
+     * to them — the same shape `share.granted` and `org.unit_owner_granted` give
+     * a granter's message. Absent means no message block at all, never an empty
+     * one.
+     */
+    message?: string;
   };
   "org.unit_owner_granted": {
     /** Display name of the person who granted access */

package/src/org/README.md

@@ -61,8 +61,14 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `CanonicalPersonSchema` — A person as reported by an external source, keyed by external identity.
 - `CanonicalPosition` _(type)_
 - `CanonicalPositionSchema` — A position (seat) as reported by an external source, placed in a unit by external reference…
+- `CanonicalPositionStatus` _(type)_
+- `CanonicalPositionStatusSchema` — Seat-existence as the SOURCE reported it.
 - `CanonicalReportingEdge` _(type)_
 - `CanonicalReportingEdgeSchema` — A reporting edge (a seat reports to a manager seat) as reported by an external source.
+- `CanonicalUnresolvedManager` _(type)_
+- `CanonicalUnresolvedManagerResolution` _(type)_
+- `CanonicalUnresolvedManagerResolutionSchema` — Why a supervisory reference could not be resolved to a seat in this batch.
+- `CanonicalUnresolvedManagerSchema` — A supervisory reference the source reported that we could NOT resolve to a seat in this batch.
 - `CapabilitiesResponse` _(type)_
 - `CapabilitiesResponseSchema` — The single validated capability surface the UI reads.
 - `ChangeMemberRoleRequest` _(type)_ — Request payload for changing a member's role.
@@ -129,6 +135,10 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `ExecutionContext` _(type)_
 - `ExecutionContextSchema` — ExecutionContext — the RUN in which an intent was produced or applied.
 - `ExecutionScope` _(type)_ — Execution scope determines whose identity is used when executing actions. - 'self': Actions execute under the…
+- `ExistingPlacementFact` _(type)_
+- `ExistingPlacementFactSchema` — Where a person already sits, and on whose authority they sit there.
+- `ExistingUnitFact` _(type)_
+- `ExistingUnitFactSchema` — An org unit that already exists, with the license the engine has over it.
 - `FACT_SOURCE_TIER_PRECEDENCE` — Truth hierarchy, highest precedence first.
 - `FactMutation` _(type)_
 - `FactMutationSchema` — A single atomic fact change the engine applies to the live org graph.
@@ -301,6 +311,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `OwnershipTransferResponseSchema`
 - `OwnershipTransferStatus` _(type)_ — Status of pending ownership transfer for an organization.
 - `PermissionAuditEntry` _(type)_ — Single entry in the permission change audit log.
+- `PersonStructureOutcome` _(type)_
+- `PersonStructureOutcomeSchema` — EXACTLY ONE outcome per person in the snapshot. "Zero or one placement" would accept a proposal that simply…
 - `Phase3AuditAction` _(type)_ — Audit actions for Phase 3 workspace expansion features.
 - `Phase4AuditAction` _(type)_ — Audit actions for Phase 4 enterprise identity features.
 - `Position` _(type)_
@@ -311,6 +323,8 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `PositionSchema`
 - `PositionStatus` _(type)_
 - `PositionStatusSchema` — Lifecycle of a seat's EXISTENCE — distinct from a hiring pipeline.
+- `ProposedOrgUnit` _(type)_
+- `ProposedOrgUnitSchema` — A unit the proposal wants the org to have.
 - `Provenance` _(type)_
 - `ProvenanceSchema` — Provenance — WHO/WHAT generated an intent.
 - `ProviderStatus` _(type)_ — Provider-level configuration lifecycle.
@@ -351,10 +365,33 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `SsoStepperStep` _(type)_ — Backend-authoritative stepper step.
 - `StagedPlacement` _(type)_ — Staged member placement: the fuller org position an invitee is slotted into, applied as deferred grants when…
 - `StagedPlacementSchema` — Staged member placement: the fuller org position an invitee is slotted into, applied as deferred grants when…
+- `StructureAcceptedBy` _(type)_
+- `StructureAcceptedBySchema` — WHO accepted the fact.
+- `StructureAuthority` _(type)_
+- `StructureAuthoritySchema` — The authority axis — the ONLY axis precedence runs on: `human_confirmed` `ai_inferred` `hris_source`.
+- `StructureEvidence` _(type)_
+- `StructureEvidenceSchema` — TYPED evidence.
+- `StructureInferenceSnapshot` _(type)_
+- `StructureInferenceSnapshotSchema` — The inference INPUT: a point-in-time view of the PERSISTED canonical graph.
+- `StructurePersonFact` _(type)_
+- `StructurePersonFactSchema` — A person as the inference engine sees them.
+- `StructureProposal` _(type)_
+- `StructureProposalOrigin` _(type)_
+- `StructureProposalOriginSchema` — How a structural fact came to be PROPOSED.
+- `StructureProposalSchema` — A proposed desired state for one org.
+- `StructureProvenance` _(type)_
+- `StructureProvenanceSchema` — The three axes together, as one accepted structural fact records them. - v1 — AI proposes, an admin clicks…
+- `StructureReportingFact` _(type)_
+- `StructureReportingFactSchema` — One reporting edge, at person granularity.
+- `StructureReviewItem` _(type)_
+- `StructureReviewItemSchema` — A question the engine is asking a human, with the competing signals attached.
+- `StructureUnitAuthority` _(type)_
+- `StructureUnitAuthoritySchema` — How much license the engine has over an EXISTING unit or placement.
 - `SubmitInteractiveTaskResponse` _(type)_
 - `SubmitInteractiveTaskResponseSchema` — Response for submitting a filled-in interactive chat task surface (e.g. the editable "change reporting…
 - `SyncRunSummary` _(type)_
 - `SyncRunSummarySchema`
+- `TOPOLOGY_ONLY_EVIDENCE_KINDS` — Evidence kinds that alone are NOT sufficient to justify a unit boundary.
 - `TRANSFER_RESPONSIBILITIES` — Responsibility checklist items shown on the acceptance page.
 - `TestSsoInitiation` _(type)_ — Initiation payload for a test SSO login attempt.
 - `TestSsoInitiationDto` _(type)_ — Initiation payload for a test SSO login attempt.
@@ -424,6 +461,7 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `WorkspaceSsoState` _(type)_ — Workspace SSO state derived from provider status + policy.
 - `WorkspaceSurface` _(type)_ — Discriminator for workspace surface routing. - 'info': Read-only surface, any member, org.view capabilities -…
 - `getViewScope` — Get the required scope for a view, or null if public.
+- `mayOverrideAuthority` — True when `incoming` may overwrite a fact currently held at `existing`.
 - `orderTreeNodes`
 
 <!-- END GENERATED: readme-public-api -->

package/src/org/__tests__/canonical-facts.test.ts

@@ -6,6 +6,7 @@ import {
   CanonicalPositionSchema,
   CanonicalOccupancySchema,
   CanonicalReportingEdgeSchema,
+  CanonicalUnresolvedManagerSchema,
   CanonicalFactsSchema,
 } from "../canonical-facts.js";
 
@@ -105,12 +106,14 @@ describe("CanonicalPositionSchema", () => {
     externalSourceSystem: "workday",
     title: "Staff Engineer",
     unitExternalSourceId: "dept-9",
+    status: "filled",
     provenance,
   };
 
   it("parses a seat placed in a unit by external reference", () => {
     const p = CanonicalPositionSchema.parse(base);
     expect(p.unitExternalSourceId).toBe("dept-9");
+    expect(p.status).toBe("filled");
   });
 
   it("rejects an empty title or missing unit reference", () => {
@@ -120,6 +123,95 @@ describe("CanonicalPositionSchema", () => {
     const { unitExternalSourceId: _u, ...without } = base;
     expect(() => CanonicalPositionSchema.parse(without)).toThrow();
   });
+
+  it("accepts every reported seat-existence value", () => {
+    for (const status of ["planned", "open", "filled"]) {
+      expect(CanonicalPositionSchema.parse({ ...base, status }).status).toBe(
+        status,
+      );
+    }
+  });
+
+  it("requires status — an adapter that cannot say must say 'filled'", () => {
+    const { status: _s, ...without } = base;
+    expect(() => CanonicalPositionSchema.parse(without)).toThrow();
+  });
+
+  it("rejects a status outside the reported-existence axis", () => {
+    // `closed` is an in-graph lifecycle outcome, not something a source reports.
+    expect(() =>
+      CanonicalPositionSchema.parse({ ...base, status: "closed" }),
+    ).toThrow();
+  });
+});
+
+describe("CanonicalUnresolvedManagerSchema", () => {
+  const base = {
+    externalSourceId: "unresolved-mgr-42",
+    externalSourceSystem: "bamboohr",
+    externalManagerId: "42",
+    reportPositionExternalSourceIds: ["pos-7", "pos-8"],
+    provenance,
+  };
+
+  it("parses a dangling supervisor reference with its report seats", () => {
+    const u = CanonicalUnresolvedManagerSchema.parse(base);
+    expect(u.externalManagerId).toBe("42");
+    expect(u.reportPositionExternalSourceIds).toEqual(["pos-7", "pos-8"]);
+  });
+
+  it("defaults resolution to 'unknown' — never to a vacancy", () => {
+    expect(CanonicalUnresolvedManagerSchema.parse(base).resolution).toBe(
+      "unknown",
+    );
+  });
+
+  it("records a vacancy only when the source says so", () => {
+    expect(
+      CanonicalUnresolvedManagerSchema.parse({
+        ...base,
+        resolution: "vacant_position",
+      }).resolution,
+    ).toBe("vacant_position");
+  });
+
+  it("accepts the remaining causes, which are not interchangeable", () => {
+    for (const resolution of ["inactive_employee", "not_visible"]) {
+      expect(
+        CanonicalUnresolvedManagerSchema.parse({ ...base, resolution })
+          .resolution,
+      ).toBe(resolution);
+    }
+  });
+
+  it("rejects an unknown resolution cause", () => {
+    expect(() =>
+      CanonicalUnresolvedManagerSchema.parse({
+        ...base,
+        resolution: "terminated",
+      }),
+    ).toThrow();
+  });
+
+  it("requires the unresolvable manager id and a provenance envelope", () => {
+    expect(() =>
+      CanonicalUnresolvedManagerSchema.parse({
+        ...base,
+        externalManagerId: "",
+      }),
+    ).toThrow();
+    const { provenance: _omitted, ...without } = base;
+    expect(() => CanonicalUnresolvedManagerSchema.parse(without)).toThrow();
+  });
+
+  it("accepts an empty report list (the reference dangles on its own)", () => {
+    expect(
+      CanonicalUnresolvedManagerSchema.parse({
+        ...base,
+        reportPositionExternalSourceIds: [],
+      }).reportPositionExternalSourceIds,
+    ).toEqual([]);
+  });
 });
 
 describe("CanonicalOccupancySchema", () => {
@@ -187,9 +279,11 @@ describe("CanonicalFactsSchema", () => {
       positions: [],
       occupancies: [],
       reportingEdges: [],
+      unresolvedManagers: [],
     });
     expect(facts.people).toEqual([]);
     expect(facts.reportingEdges).toEqual([]);
+    expect(facts.unresolvedManagers).toEqual([]);
   });
 
   it("parses a populated batch with one of each fact", () => {
@@ -216,6 +310,7 @@ describe("CanonicalFactsSchema", () => {
           externalSourceSystem: "workday",
           title: "Staff Engineer",
           unitExternalSourceId: "dept-9",
+          status: "filled",
           provenance,
         },
       ],
@@ -238,9 +333,19 @@ describe("CanonicalFactsSchema", () => {
           provenance,
         },
       ],
+      unresolvedManagers: [
+        {
+          externalSourceId: "unresolved-mgr-42",
+          externalSourceSystem: "bamboohr",
+          externalManagerId: "42",
+          reportPositionExternalSourceIds: ["pos-7"],
+          provenance,
+        },
+      ],
     });
     expect(facts.people).toHaveLength(1);
     expect(facts.positions[0].unitExternalSourceId).toBe("dept-9");
+    expect(facts.unresolvedManagers[0].resolution).toBe("unknown");
   });
 
   it("requires every array key to be present", () => {
@@ -249,6 +354,18 @@ describe("CanonicalFactsSchema", () => {
     ).toThrow();
   });
 
+  it("requires the unresolvedManagers channel — silence is not an option", () => {
+    expect(() =>
+      CanonicalFactsSchema.parse({
+        people: [],
+        orgUnits: [],
+        positions: [],
+        occupancies: [],
+        reportingEdges: [],
+      }),
+    ).toThrow();
+  });
+
   it("rejects a member that fails its element schema", () => {
     expect(() =>
       CanonicalFactsSchema.parse({
@@ -264,6 +381,7 @@ describe("CanonicalFactsSchema", () => {
         positions: [],
         occupancies: [],
         reportingEdges: [],
+        unresolvedManagers: [],
       }),
     ).toThrow();
   });