@company-semantics/contracts 18.1.1 → 19.0.0

package/package.json

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

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 = '4944d64336bd' as const;
-export const SPEC_HASH_FULL = '4944d64336bd97c454ceef9917209bd1da7bab66a771e02c91bafec5ab31d47e' as const;
+export const SPEC_HASH = '814c99a18543' as const;
+export const SPEC_HASH_FULL = '814c99a18543f448daaed5312db276f7704a9b63710c512b1a298be5fc652105' as const;

package/src/api/generated.ts

@@ -4745,6 +4745,11 @@ export interface components {
                 jobTitle: string | null;
                 avatarUrl: string | null;
                 primaryUnitId: string | null;
+                ownedUnits: {
+                    /** Format: uuid */
+                    id: string;
+                    name: string;
+                }[];
             }[];
             edges: {
                 /** Format: uuid */

package/src/identity/README.md

@@ -44,6 +44,8 @@ TypeScript types and functions for user identity and display name resolution.
 - `BannerDismissedListResponseSchema`
 - `DeletionBlocker` _(type)_ — Conditions that block account deletion.
 - `ISODateString` _(type)_ — ISO 8601 date-time string.
+- `IdentityLink` _(type)_
+- `IdentityLinkSchema`
 - `MeResponse` _(type)_
 - `MeResponseSchema` — Full identity context returned by GET /api/me.
 - `NameSource` _(type)_ — Source of the user's name data.
@@ -53,8 +55,12 @@ TypeScript types and functions for user identity and display name resolution.
 - `PeopleOrgChartNodeSchema`
 - `PeopleOrgChartOpenRole` _(type)_
 - `PeopleOrgChartOpenRoleSchema`
+- `PeopleOrgChartOwnedUnit` _(type)_
+- `PeopleOrgChartOwnedUnitSchema`
 - `PeopleOrgChartResponse` _(type)_
 - `PeopleOrgChartResponseSchema`
+- `Person` _(type)_
+- `PersonSchema`
 - `ProfileResponse` _(type)_
 - `ProfileResponseSchema`
 - `ReportingRelationshipType` _(type)_

package/src/identity/__tests__/identity-link.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { IdentityLinkSchema } from "../identity-link.js";
+
+const validLink = {
+  id: "11111111-1111-4111-8111-111111111111",
+  orgId: "22222222-2222-4222-8222-222222222222",
+  provider: "bamboohr",
+  externalId: "emp-4081",
+  personId: "33333333-3333-4333-8333-333333333333",
+  createdAt: "2026-06-21T10:00:00.000Z",
+  updatedAt: "2026-06-21T10:00:00.000Z",
+};
+
+describe("IdentityLinkSchema", () => {
+  it("accepts a valid identity link record", () => {
+    expect(IdentityLinkSchema.parse(validLink)).toEqual(validLink);
+  });
+
+  it("accepts arbitrary provider strings (open vocabulary)", () => {
+    for (const provider of ["bamboohr", "workday", "scim", "custom-hris"]) {
+      expect(
+        IdentityLinkSchema.safeParse({ ...validLink, provider }).success,
+      ).toBe(true);
+    }
+  });
+
+  it("rejects an empty provider", () => {
+    expect(
+      IdentityLinkSchema.safeParse({ ...validLink, provider: "" }).success,
+    ).toBe(false);
+  });
+
+  it("rejects an empty externalId", () => {
+    expect(
+      IdentityLinkSchema.safeParse({ ...validLink, externalId: "" }).success,
+    ).toBe(false);
+  });
+
+  it("rejects a non-uuid personId", () => {
+    expect(
+      IdentityLinkSchema.safeParse({ ...validLink, personId: "not-a-uuid" })
+        .success,
+    ).toBe(false);
+  });
+
+  it("rejects a non-datetime createdAt", () => {
+    expect(
+      IdentityLinkSchema.safeParse({ ...validLink, createdAt: "yesterday" })
+        .success,
+    ).toBe(false);
+  });
+});

package/src/identity/__tests__/person.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+
+import { PersonSchema } from "../person.js";
+
+describe("PersonSchema", () => {
+  const base = {
+    id: "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
+    orgId: "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b",
+    displayName: "Ada Lovelace",
+  };
+
+  it("parses a minimal accountless person", () => {
+    const person = PersonSchema.parse(base);
+    expect(person.displayName).toBe("Ada Lovelace");
+    expect(person.userId).toBeUndefined();
+  });
+
+  it("accepts a null userId (accountless) and a uuid userId (linked)", () => {
+    expect(PersonSchema.parse({ ...base, userId: null }).userId).toBeNull();
+    const linked = PersonSchema.parse({
+      ...base,
+      userId: "9c5b94b1-35ad-49bb-b118-8e8fc24abf80",
+    });
+    expect(linked.userId).toBe("9c5b94b1-35ad-49bb-b118-8e8fc24abf80");
+  });
+
+  it("accepts a null primaryEmail and validates email format", () => {
+    expect(
+      PersonSchema.parse({ ...base, primaryEmail: null }).primaryEmail,
+    ).toBeNull();
+    expect(() =>
+      PersonSchema.parse({ ...base, primaryEmail: "not-an-email" }),
+    ).toThrow();
+  });
+
+  it("rejects an empty displayName and non-uuid id", () => {
+    expect(() => PersonSchema.parse({ ...base, displayName: "" })).toThrow();
+    expect(() => PersonSchema.parse({ ...base, id: "nope" })).toThrow();
+  });
+});

package/src/identity/identity-link.ts

@@ -0,0 +1,38 @@
+/**
+ * Identity Link Vocabulary
+ *
+ * An IdentityLink is a durable map from an external system's identifier to a
+ * Person in the org graph. It generalizes the legacy
+ * `users.external_source_id` / `users.external_source_system` pair into a
+ * first-class, per-source record: a BambooHR link is simply an IdentityLink
+ * with `provider: 'bamboohr'`.
+ *
+ * `provider` is an OPEN string (e.g. 'bamboohr', 'workday', 'scim') rather than
+ * an enum, so onboarding a new identity source needs no schema change.
+ *
+ * Logical uniqueness is the tuple (orgId, provider, externalId): a given
+ * external id from a given provider, within a given org, maps to exactly one
+ * Person. The (orgId, provider, externalId) tuple is the natural key.
+ *
+ * @see ADR-CONT-032 for identity vocabulary design rationale
+ */
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// IdentityLink — external system id → Person
+// ---------------------------------------------------------------------------
+
+export const IdentityLinkSchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid(),
+  // Open string (NOT an enum) so new sources need no schema change.
+  provider: z.string().min(1),
+  // The opaque identifier the external system uses for this person.
+  externalId: z.string().min(1),
+  // The Person this external identity resolves to (Person.id).
+  personId: z.string().uuid(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+});
+
+export type IdentityLink = z.infer<typeof IdentityLinkSchema>;

package/src/identity/index.ts

@@ -65,6 +65,7 @@ export type {
 export {
   ReportingRelationshipTypeSchema,
   PeopleOrgChartNodeSchema,
+  PeopleOrgChartOwnedUnitSchema,
   PeopleOrgChartEdgeSchema,
   PeopleOrgChartOpenRoleSchema,
   PeopleOrgChartResponseSchema,
@@ -72,7 +73,16 @@ export {
 export type {
   ReportingRelationshipType,
   PeopleOrgChartNode,
+  PeopleOrgChartOwnedUnit,
   PeopleOrgChartEdge,
   PeopleOrgChartOpenRole,
   PeopleOrgChartResponse,
 } from "./people-org-chart";
+
+// Person — the org-graph node for a human (0..1 User link), per ADR-CTRL-182
+export { PersonSchema } from "./person";
+export type { Person } from "./person";
+
+// Identity Link — external system id → Person (provider is an open string)
+export { IdentityLinkSchema } from "./identity-link";
+export type { IdentityLink } from "./identity-link";

package/src/identity/people-org-chart.ts

@@ -26,12 +26,30 @@ export type ReportingRelationshipType = z.infer<
 // Node — a person in the chart
 // ---------------------------------------------------------------------------
 
+// A unit this person is a *local structural owner* of — i.e. holds a grant with
+// `authority_source = 'structural'` directly on that unit (ADR-BE-168). Carries
+// the unit name so the chart can render an owner tooltip ("Unit owner of …")
+// without a second lookup. The org root unit appears here for the account
+// owner(s) (the CEO), whom the chart marks with the owner icon instead.
+export const PeopleOrgChartOwnedUnitSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+});
+
+export type PeopleOrgChartOwnedUnit = z.infer<
+  typeof PeopleOrgChartOwnedUnitSchema
+>;
+
 export const PeopleOrgChartNodeSchema = z.object({
   id: z.string().uuid(),
   fullName: z.string(),
   jobTitle: z.string().nullable(),
   avatarUrl: z.string().nullable(),
   primaryUnitId: z.string().uuid().nullable(),
+  // Units this person is a local structural owner of. Empty ⇒ not a unit owner.
+  // Drives the chart's owner key + tooltip; the account owner (root-unit owner)
+  // is rendered with the org owner icon (crown) instead.
+  ownedUnits: z.array(PeopleOrgChartOwnedUnitSchema),
 });
 
 export type PeopleOrgChartNode = z.infer<typeof PeopleOrgChartNodeSchema>;

package/src/identity/person.ts

@@ -0,0 +1,28 @@
+/**
+ * Person Identity Vocabulary
+ *
+ * Person: the human in the org — the org-graph node. Distinct from `User` (an
+ * authenticated account). A Person has 0..1 linked User (`userId`); accountless
+ * People are valid from day one. Identity vocabulary, NOT a structure fact, so it
+ * carries no FactProvenance envelope. See control ADR-CTRL-182.
+ */
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Person — the org-graph node for a human, with an optional 0..1 User link
+// ---------------------------------------------------------------------------
+
+export const PersonSchema = z.object({
+  /** Unique identifier for the person within the org graph. */
+  id: z.string().uuid(),
+  /** Owning organization (tenant) this person belongs to. */
+  orgId: z.string().uuid(),
+  /** Human-facing name of the person in the org. */
+  displayName: z.string().min(1),
+  /** Primary email if known; null for people imported without one. */
+  primaryEmail: z.string().email().nullable().optional(),
+  /** The authenticated account this person is, if any (0..1). Null when accountless. */
+  userId: z.string().uuid().nullable().optional(),
+});
+
+export type Person = z.infer<typeof PersonSchema>;

package/src/index.ts

@@ -171,6 +171,7 @@ export type {
 export {
   ReportingRelationshipTypeSchema,
   PeopleOrgChartNodeSchema,
+  PeopleOrgChartOwnedUnitSchema,
   PeopleOrgChartEdgeSchema,
   PeopleOrgChartOpenRoleSchema,
   PeopleOrgChartResponseSchema,
@@ -178,11 +179,20 @@ export {
 export type {
   ReportingRelationshipType,
   PeopleOrgChartNode,
+  PeopleOrgChartOwnedUnit,
   PeopleOrgChartEdge,
   PeopleOrgChartOpenRole,
   PeopleOrgChartResponse,
 } from "./identity/index";
 
+// Person — the org-graph node for a human (0..1 User link), per ADR-CTRL-182
+export { PersonSchema } from "./identity/index";
+export type { Person } from "./identity/index";
+
+// Identity Link — external system id → Person (provider is an open string)
+export { IdentityLinkSchema } from "./identity/index";
+export type { IdentityLink } from "./identity/index";
+
 // Auth domain types
 export type { AuthStartMode, AuthStartResponse } from "./auth/index";
 export { OTPErrorCode } from "./auth/index";

package/src/org/structure-facts.ts

@@ -76,6 +76,15 @@ export const FactProvenanceSchema = z.object({
    * for an original. Enables append+supersede without destructive updates.
    */
   supersedesFactId: z.string().uuid().nullable().optional(),
+  /**
+   * Human-meaningful WHY for a deliberate human edit — a free-text audit
+   * record of intent, capped at 2000 chars to mirror the delegation-note /
+   * unit-owner reason API cap. `null`/absent for machine-sourced facts (sync,
+   * import, inference). It is an audit record of intent, NOT an authorization
+   * grant: it explains why a fact was set, never who may act on it
+   * (ADR-CTRL-180).
+   */
+  reason: z.string().max(2000).nullable().optional(),
 });
 export type FactProvenance = z.infer<typeof FactProvenanceSchema>;