@company-semantics/contracts 13.16.0 → 13.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "13.16.0",
+  "version": "13.18.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -64,6 +64,10 @@
       "types": "./src/impersonation/index.ts",
       "default": "./src/impersonation/index.ts"
     },
+    "./ingestion": {
+      "types": "./src/ingestion/index.ts",
+      "default": "./src/ingestion/index.ts"
+    },
     "./schemas/guard-result.schema.json": "./schemas/guard-result.schema.json"
   },
   "types": "./src/index.ts",

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

@@ -31,6 +31,34 @@ describe("resource-keys: orgUnitOwners (org-scoped)", () => {
   });
 });
 
+describe("resource-keys: orgUnitOpenRoles (per-unit identity)", () => {
+  const UNIT_ID = "33333333-3333-4333-8333-333333333333";
+  const key: ResourceKey = {
+    type: "orgUnitOpenRoles",
+    orgId: ORG_ID,
+    unitId: UNIT_ID,
+  };
+
+  it("toQueryKey produces [type, orgId, unitId]", () => {
+    const qk = toQueryKey(key);
+    expect(qk).toEqual(["orgUnitOpenRoles", ORG_ID, UNIT_ID]);
+    expect(qk).toHaveLength(3);
+  });
+
+  it("roundtrips through fromQueryKey", () => {
+    const parsed = fromQueryKey(toQueryKey(key));
+    expect(parsed).toEqual(key);
+  });
+
+  it("matchesResourceKey is unitId-scoped: rejects a different unit", () => {
+    const otherUnit = "44444444-4444-4444-8444-444444444444";
+    expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
+    expect(
+      matchesResourceKey(["orgUnitOpenRoles", ORG_ID, otherUnit], key),
+    ).toBe(false);
+  });
+});
+
 describe("resource-keys: system-scoped internalAdmin* types", () => {
   const systemTypes = [
     "internalAdminAiProviders",

package/src/api/generated.ts

@@ -1972,6 +1972,24 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/org-units/{unitId}/head": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /** Pin an explicit head (anchor person) for an org unit */
+        put: operations["setOrgUnitHead"];
+        post?: never;
+        /** Revert an org unit head to the system-inferred default */
+        delete: operations["revertOrgUnitHead"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/org-units/{unitId}/my-authority": {
         parameters: {
             query?: never;
@@ -4287,6 +4305,8 @@ export interface components {
                     count: number;
                     userIds: string[];
                 } | null;
+                headUserId: string | null;
+                headOrigin: ("user" | "inferred") | null;
             }[];
         };
         OrgUnitDescendantsResponse: {
@@ -4435,6 +4455,8 @@ export interface components {
                     count: number;
                     userIds: string[];
                 } | null;
+                headUserId: string | null;
+                headOrigin: ("user" | "inferred") | null;
             }[];
             levelConfig: {
                 /** Format: uuid */
@@ -4579,6 +4601,12 @@ export interface components {
             revokedAt: string | null;
             reason: string | null;
         };
+        UnitHeadResponse: {
+            /** Format: uuid */
+            unitId: string;
+            headUserId: string | null;
+            origin: ("user" | "inferred") | null;
+        };
         OrgUnitMyAuthorityResponse: {
             /** Format: uuid */
             unitId: string;
@@ -4693,6 +4721,14 @@ export interface components {
                 unitId: string;
                 title: string | null;
             }[];
+            unitHeads: {
+                /** Format: uuid */
+                unitId: string;
+                /** Format: uuid */
+                headUserId: string;
+                /** @enum {string} */
+                origin: "user" | "inferred";
+            }[];
         };
         /** @description Polling snapshot of a generic ingestion operation. */
         IngestionOperationPollResponse: {
@@ -8444,6 +8480,57 @@ export interface operations {
             };
         };
     };
+    setOrgUnitHead: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** Format: uuid */
+                    userId: string;
+                };
+            };
+        };
+        responses: {
+            /** @description The pinned unit head */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["UnitHeadResponse"];
+                };
+            };
+        };
+    };
+    revertOrgUnitHead: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                unitId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The re-inferred unit head (or null when none resolves) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["UnitHeadResponse"];
+                };
+            };
+        };
+    };
     getMyOrgUnitAuthority: {
         parameters: {
             query?: never;

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

@@ -69,7 +69,7 @@ export type PeopleOrgChartOpenRole = z.infer<
 // ---------------------------------------------------------------------------
 // Unit head — the person a unit (and its person-less children: empty-unit
 // placeholders, pending-invite ghosts, open-role seats) anchors under in the
-// people chart. A presentation/anchor "tether" (ADR-BE-283), NOT authority.
+// people chart. A presentation/anchor "tether" (ADR-BE-284), NOT authority.
 // `origin` distinguishes an explicit user choice from a system-inferred default
 // so the UI can render "Pinned" vs "Auto" and offer revert-to-auto. The client
 // prefers the head of a unit's PARENT when anchoring its person-less children,

package/src/index.ts

@@ -779,3 +779,8 @@ export * from "./meetings";
 // AccessLevel / OrgChartRole / AccessSource — see ADR-CTRL-084..088.
 // No consumers in this PRD; cutover starts in AUTH-002 (PRD-00670).
 export * from "./permissions";
+
+// Document-ingestion accept-set vocabulary — see ADR-CONT-075.
+// Single source of truth for upload formats; the backend normalizer joins its
+// private dispatch fields locally, the app derives its accept-set + copy.
+export * from "./ingestion";

package/src/ingestion/README.md

@@ -0,0 +1,35 @@
+# ingestion/
+
+Shared vocabulary for the document-ingestion accept-set.
+
+## Purpose
+
+The single source of truth for which file formats the platform accepts for
+upload — their MIME types, filename extensions, human label groups, and
+per-format byte caps. The backend normalizer joins these entries with its
+private dispatch table; the app upload UI derives its file-input `accept`
+attribute and supported-formats copy from the same data.
+
+## Invariants
+
+- `INGESTION_FORMATS` is the canonical list; `mime` is unique across entries.
+- Entries are ordered text → documents → images/diagrams → audio/video. The
+  backend's MIME-order test and the derived UI strings depend on this order.
+- `INGEST_ACCEPT` and `SUPPORTED_LABEL` are **derived** from the registry, never
+  hand-maintained — adding a format updates both automatically.
+- No normalizer-routing fields here (`canonicalKind`, `normalizerKey` are
+  backend-only). This package stays pure vocabulary.
+
+## Public API
+
+- `IngestionFormat` — `{ mime, extensions, label, maxBytes }`.
+- `INGESTION_FORMATS: readonly IngestionFormat[]`.
+- `byMime(mime)`, `acceptExtensions()`, `humanLabels()`.
+- `INGEST_ACCEPT: string` — comma-joined extensions for an `accept` attribute.
+- `SUPPORTED_LABEL: string` — human-readable supported-formats summary.
+
+## Dependencies
+
+None beyond `./types`. (The backend registry at
+`company-semantics-backend/src/orgs/ingestion/normalize/format-registry.ts`
+consumes this and adds its private dispatch fields.)

package/src/ingestion/__tests__/registry.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import {
+  INGESTION_FORMATS,
+  byMime,
+  acceptExtensions,
+  humanLabels,
+  INGEST_ACCEPT,
+  SUPPORTED_LABEL,
+} from "../registry";
+
+describe("ingestion registry", () => {
+  it("has a unique MIME per entry", () => {
+    const mimes = INGESTION_FORMATS.map((e) => e.mime);
+    expect(new Set(mimes).size).toBe(mimes.length);
+  });
+
+  it("uses lowercase, dot-prefixed extensions", () => {
+    for (const entry of INGESTION_FORMATS) {
+      for (const ext of entry.extensions) {
+        expect(ext).toMatch(/^\.[a-z0-9]+$/);
+      }
+    }
+  });
+
+  it("byMime resolves a known format and rejects unknown", () => {
+    expect(byMime("application/pdf")?.label).toBe("PDF");
+    expect(byMime("audio/mpeg")?.label).toBe("Audio");
+    expect(byMime("application/x-unknown")).toBeUndefined();
+  });
+
+  it("derives INGEST_ACCEPT from every extension in registry order", () => {
+    expect(INGEST_ACCEPT).toBe(acceptExtensions().join(","));
+    expect(INGEST_ACCEPT).toBe(
+      ".txt,.md,.html,.htm,.csv,.rtf,.docx,.doc,.pptx,.xlsx,.odt,.pdf,.png,.jpg,.jpeg,.webp,.gif,.heic,.svg,.drawio,.mp3,.m4a,.wav,.aac,.mp4,.m4v,.mov",
+    );
+  });
+
+  it("derives SUPPORTED_LABEL from the unique group labels", () => {
+    expect(SUPPORTED_LABEL).toBe(`Supported: ${humanLabels().join(", ")}`);
+    expect(SUPPORTED_LABEL).toBe(
+      "Supported: Text, Markdown, HTML, CSV, RTF, Word, PowerPoint, Excel, OpenDocument, PDF, Image, Diagram, Audio, Video",
+    );
+  });
+});

package/src/ingestion/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Ingestion Domain Barrel
+ *
+ * Re-exports the public document-ingestion format vocabulary.
+ * Import from '@company-semantics/contracts/ingestion'.
+ *
+ * @see ADR-CONT-075 for design rationale
+ */
+
+export type { IngestionFormat } from "./types";
+
+export {
+  INGESTION_FORMATS,
+  byMime,
+  acceptExtensions,
+  humanLabels,
+  INGEST_ACCEPT,
+  SUPPORTED_LABEL,
+} from "./registry";

package/src/ingestion/registry.ts

@@ -0,0 +1,194 @@
+/**
+ * Ingestion Format Registry
+ *
+ * THE single source of truth for the public document-ingestion accept-set. The
+ * backend normalizer joins these entries with its private dispatch table; the
+ * app derives its file-input `accept` attribute and supported-formats copy from
+ * the helpers below. Neither side re-spells the extension or label list.
+ *
+ * Invariants:
+ * - Entries are ordered text → documents → images/diagrams → audio/video; the
+ *   backend's MIME-order test and the derived UI strings depend on this order.
+ * - `INGEST_ACCEPT` and `SUPPORTED_LABEL` are DERIVED, never hand-maintained —
+ *   adding a format here updates both automatically.
+ *
+ * @see ADR-CONT-075 for design rationale
+ */
+
+import type { IngestionFormat } from "./types";
+
+/** The canonical public format registry. */
+export const INGESTION_FORMATS: readonly IngestionFormat[] = [
+  {
+    mime: "text/plain",
+    extensions: [".txt"],
+    label: "Text",
+    maxBytes: 10_000_000,
+  },
+  {
+    mime: "text/markdown",
+    extensions: [".md"],
+    label: "Markdown",
+    maxBytes: 10_000_000,
+  },
+  {
+    mime: "text/html",
+    extensions: [".html", ".htm"],
+    label: "HTML",
+    maxBytes: 10_000_000,
+  },
+  {
+    mime: "text/csv",
+    extensions: [".csv"],
+    label: "CSV",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "application/rtf",
+    extensions: [".rtf"],
+    label: "RTF",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    extensions: [".docx"],
+    label: "Word",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "application/msword",
+    extensions: [".doc"],
+    label: "Word",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    extensions: [".pptx"],
+    label: "PowerPoint",
+    maxBytes: 50_000_000,
+  },
+  {
+    mime: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    extensions: [".xlsx"],
+    label: "Excel",
+    maxBytes: 50_000_000,
+  },
+  {
+    mime: "application/vnd.oasis.opendocument.text",
+    extensions: [".odt"],
+    label: "OpenDocument",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "application/pdf",
+    extensions: [".pdf"],
+    label: "PDF",
+    maxBytes: 50_000_000,
+  },
+  {
+    mime: "image/png",
+    extensions: [".png"],
+    label: "Image",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "image/jpeg",
+    extensions: [".jpg", ".jpeg"],
+    label: "Image",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "image/webp",
+    extensions: [".webp"],
+    label: "Image",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "image/gif",
+    extensions: [".gif"],
+    label: "Image",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "image/heic",
+    extensions: [".heic"],
+    label: "Image",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "image/svg+xml",
+    extensions: [".svg"],
+    label: "Diagram",
+    maxBytes: 10_000_000,
+  },
+  {
+    mime: "application/vnd.jgraph.mxfile",
+    extensions: [".drawio"],
+    label: "Diagram",
+    maxBytes: 10_000_000,
+  },
+  {
+    mime: "audio/mpeg",
+    extensions: [".mp3"],
+    label: "Audio",
+    maxBytes: 500_000_000,
+  },
+  {
+    mime: "audio/x-m4a",
+    extensions: [".m4a"],
+    label: "Audio",
+    maxBytes: 500_000_000,
+  },
+  {
+    mime: "audio/wav",
+    extensions: [".wav"],
+    label: "Audio",
+    maxBytes: 500_000_000,
+  },
+  {
+    mime: "audio/aac",
+    extensions: [".aac"],
+    label: "Audio",
+    maxBytes: 500_000_000,
+  },
+  {
+    mime: "video/mp4",
+    extensions: [".mp4", ".m4v"],
+    label: "Video",
+    maxBytes: 500_000_000,
+  },
+  {
+    mime: "video/quicktime",
+    extensions: [".mov"],
+    label: "Video",
+    maxBytes: 500_000_000,
+  },
+];
+
+/** Look up the entry for a canonical MIME; undefined means unsupported. */
+export function byMime(mime: string): IngestionFormat | undefined {
+  return INGESTION_FORMATS.find((entry) => entry.mime === mime);
+}
+
+/** All accepted filename extensions, in registry order. */
+export function acceptExtensions(): string[] {
+  return INGESTION_FORMATS.flatMap((entry) => [...entry.extensions]);
+}
+
+/** Unique group labels for human display, in registry order. */
+export function humanLabels(): string[] {
+  return [...new Set(INGESTION_FORMATS.map((entry) => entry.label))];
+}
+
+/**
+ * Comma-joined extension string for a file input's `accept` attribute.
+ * Derived from {@link acceptExtensions} — never hand-maintained.
+ */
+export const INGEST_ACCEPT: string = acceptExtensions().join(",");
+
+/**
+ * Human-readable supported-formats summary, derived from {@link humanLabels}.
+ * Names every accepted group (in registry order) so the copy can't undersell
+ * what actually works.
+ */
+export const SUPPORTED_LABEL: string = `Supported: ${humanLabels().join(", ")}`;

package/src/ingestion/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Ingestion Format Types
+ *
+ * The public vocabulary for the document-ingestion accept-set: which file
+ * formats the platform accepts for upload, their human label groups, and the
+ * per-format byte caps. Shared by the backend normalizer (which adds its own
+ * private dispatch fields locally) and the app upload UI (which derives its
+ * `accept` attribute and supported-formats copy from this).
+ *
+ * Types only — no runtime behavior. The backend-only normalizer routing
+ * (`canonicalKind`, `normalizerKey`) deliberately does NOT live here; it is an
+ * implementation detail of the backend dispatch and would pollute the shared
+ * vocabulary.
+ *
+ * @see ADR-CONT-075 for design rationale
+ */
+
+/**
+ * One accepted upload format, keyed by its canonical MIME type.
+ *
+ * Invariants:
+ * - `mime` is unique across the registry.
+ * - `extensions` are lowercase, dot-prefixed (e.g. `.docx`).
+ * - `label` is the human display GROUP and is intentionally shared across
+ *   related formats (`.docx` + `.doc` are both `Word`; the rasters are all
+ *   `Image`; `.svg` + `.drawio` are `Diagram`).
+ */
+export interface IngestionFormat {
+  /** Canonical MIME type (the registry key). */
+  mime: string;
+  /** Lowercase, dot-prefixed filename extensions for this format. */
+  extensions: readonly string[];
+  /** Human display group label (e.g. `Word`, `Image`, `Audio`). */
+  label: string;
+  /** Per-format upload byte cap. */
+  maxBytes: number;
+}

package/src/org/schemas.ts

@@ -948,7 +948,7 @@ export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
   openRoleCount: z.number().int().min(0),
   missingAtNextLevel: MissingAtNextLevelSchema.nullable(),
   /**
-   * The unit head (ADR-BE-283): the person this unit (and its person-less
+   * The unit head (ADR-BE-284): the person this unit (and its person-less
    * children) anchors under in the people chart — a presentation "tether", NOT
    * authority. `headUserId` is null when no head is resolved (e.g. an empty
    * unit with no members). `headOrigin` is `'user'` for an explicit choice,

package/src/resource-keys.ts

@@ -36,6 +36,11 @@ export type ResourceKey =
   | { type: "orgUnitAncestors"; orgId: string; unitId: string }
   | { type: "orgUnitMemberships"; orgId: string; unitId: string }
   | { type: "orgUnitPermissions"; orgId: string; unitId: string }
+  // Open roles seated in a unit (ADR-BE-277) — a per-unit list, unitId-scoped
+  // like memberships/permissions. Read in the unit members view and the
+  // org-chart card; refreshed as a graph target of orgTree on structural
+  // mutations (create / advance lifecycle / fill). See ADR-CONTRACTS-065.
+  | { type: "orgUnitOpenRoles"; 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 }
@@ -145,6 +150,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "orgUnitAncestors":
     case "orgUnitMemberships":
     case "orgUnitPermissions":
+    case "orgUnitOpenRoles":
       return [key.type, key.orgId, key.unitId] as const;
 
     // User-scoped
@@ -218,6 +224,7 @@ export function fromQueryKey(queryKey: readonly string[]): ResourceKey {
     orgUnitAncestors: "unitId",
     orgUnitMemberships: "unitId",
     orgUnitPermissions: "unitId",
+    orgUnitOpenRoles: "unitId",
   };
 
   if (type in identityFields) {