@company-semantics/contracts 13.19.0 → 13.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "13.19.0",
+  "version": "13.20.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -119,15 +119,15 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^22.19.20",
+    "@types/node": "^25.9.3",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.7",
     "markdownlint-cli2": "^0.22.1",
     "openapi-typescript": "^7.13.0",
-    "prettier": "^3.8.3",
+    "prettier": "^3.8.4",
     "tsx": "^4.22.4",
     "typescript": "^5.8.3",
-    "vitest": "^4.1.8",
+    "vitest": "^4.1.9",
     "yaml": "^2.9.0"
   },
   "pnpm": {

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 = 'b4c6a72ecef5' as const;
-export const SPEC_HASH_FULL = 'b4c6a72ecef5397ac7bffd8e6d1638ffa91d8e917e683ca31b1b71a356cd080e' as const;
+export const SPEC_HASH = '255ee9f997af' as const;
+export const SPEC_HASH_FULL = '255ee9f997afb36f3e96cdcffb8aa30a97e5c14f8c21b884974c75f9d126d596' as const;

package/src/api/generated.ts

@@ -3376,7 +3376,7 @@ export interface components {
             };
             ownerTitle: string;
             /** @enum {string} */
-            ownerIcon: "crown" | "crown-cross" | "person" | "medal-military" | "dog" | "cat";
+            ownerIcon: "crown" | "crown-cross" | "person-simple-run" | "person" | "medal-military" | "dog" | "cat" | "linux-logo";
             createdAt: string;
             memberCount: number;
             claimable: boolean;
@@ -3390,7 +3390,7 @@ export interface components {
         OrgRenameRequest: {
             name?: string;
             ownerTitle?: string | null;
-            ownerIcon?: ("crown" | "crown-cross" | "person" | "medal-military" | "dog" | "cat") | null;
+            ownerIcon?: ("crown" | "crown-cross" | "person-simple-run" | "person" | "medal-military" | "dog" | "cat" | "linux-logo") | null;
         };
         WorkspaceMembersResponse: {
             items: {
@@ -4051,6 +4051,11 @@ export interface components {
                         state: "allowed" | "blocked";
                         requiredScope?: string;
                     };
+                    manageSharing: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
                 };
                 workItem?: {
                     transferOwnership: {
@@ -4058,6 +4063,18 @@ export interface components {
                         state: "allowed" | "blocked";
                         requiredScope?: string;
                     };
+                    manageSharing: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
+                };
+                meetingRecording?: {
+                    manageSharing: {
+                        /** @enum {string} */
+                        state: "allowed" | "blocked";
+                        requiredScope?: string;
+                    };
                 };
             };
         };

package/src/generated/openapi-routes.ts

@@ -82,6 +82,7 @@ export const openApiRoutes = {
   '/api/org-units/{unitId}/delegations': ['POST'],
   '/api/org-units/{unitId}/delegations/{id}': ['DELETE', 'PATCH'],
   '/api/org-units/{unitId}/descendants': ['GET'],
+  '/api/org-units/{unitId}/head': ['DELETE', 'PUT'],
   '/api/org-units/{unitId}/memberships': ['GET', 'POST'],
   '/api/org-units/{unitId}/memberships/{userId}': ['DELETE'],
   '/api/org-units/{unitId}/memberships/{userId}/role': ['PUT'],

package/src/index.ts

@@ -358,6 +358,19 @@ export {
 // View authorization types (Phase 5 - ADR-APP-013)
 export type { AuthorizableView } from "./org/index";
 
+// Org structure facts: provenance + home/membership separation (ADR-CONTRACTS-066)
+export {
+  FactSourceTierSchema,
+  FACT_SOURCE_TIER_PRECEDENCE,
+  FactProvenanceSchema,
+  HomeAssignmentSchema,
+} from "./org/index";
+export type {
+  FactSourceTier,
+  FactProvenance,
+  HomeAssignment,
+} from "./org/index";
+
 // Authority & Delegation vocabulary
 export {
   AuthoritySourceSchema,

package/src/org/index.ts

@@ -87,6 +87,19 @@ export type {
 export type { AuthorizableView } from "./view-scopes";
 export { VIEW_SCOPE_MAP, getViewScope } from "./view-scopes";
 
+// Org structure facts: provenance + home/membership separation (ADR-CONTRACTS-066)
+export {
+  FactSourceTierSchema,
+  FACT_SOURCE_TIER_PRECEDENCE,
+  FactProvenanceSchema,
+  HomeAssignmentSchema,
+} from "./structure-facts";
+export type {
+  FactSourceTier,
+  FactProvenance,
+  HomeAssignment,
+} from "./structure-facts";
+
 // Canonical OrgUnit tree ordering (PRD-00506)
 export type { TreeOrderableNode } from "./tree-ordering";
 export { orderTreeNodes } from "./tree-ordering";

package/src/org/schemas.ts

@@ -1438,16 +1438,25 @@ export const CapabilitiesResponseSchema = z.object({
       orgUnit: z.object({
         manage: ActionCapabilitySchema,
       }),
-      // Entity ownership-transfer overrides (backend ADR-BE-259). Optional so
-      // older backends that don't derive them still validate.
+      // Entity ownership-transfer overrides (backend ADR-BE-259) +
+      // sharing-management custody (backend ADR-BE-288). Optional so older
+      // backends that don't derive them still validate. manageSharing gates the
+      // admin Share affordance on content the admin may not be able to view.
       companyMd: z
         .object({
           transferOwnership: ActionCapabilitySchema,
+          manageSharing: ActionCapabilitySchema,
         })
         .optional(),
       workItem: z
         .object({
           transferOwnership: ActionCapabilitySchema,
+          manageSharing: ActionCapabilitySchema,
+        })
+        .optional(),
+      meetingRecording: z
+        .object({
+          manageSharing: ActionCapabilitySchema,
         })
         .optional(),
     })

package/src/org/structure-facts.ts

@@ -0,0 +1,105 @@
+/**
+ * Org structure facts: provenance envelope + the home/membership separation.
+ *
+ * The org model is several INDEPENDENT graphs — the org-unit tree, the reporting
+ * graph, the home assignment, and the membership graph (and, later, positions).
+ * This module is the shared vocabulary for two cross-cutting ideas in that model
+ * (see ADR-CONTRACTS-066 and control ADR-CTRL-159):
+ *
+ *  1. Every structural fact carries provenance ({@link FactProvenanceSchema}).
+ *  2. "Home" is a dedicated ≤1-per-person relation ({@link HomeAssignmentSchema}),
+ *     kept SEPARATE from `org_unit_memberships` — not a `kind` flag on memberships.
+ *
+ * Principles encoded here (do not drift from these):
+ *  - Membership / home is an INPUT to authority derivation, NOT authority itself.
+ *    `home member of unit` does not mean `owns unit`.
+ *  - Facts are immutable; corrections SUPERSEDE prior facts (`supersedesFactId`)
+ *    rather than mutating in place. This leaves room for event-sourcing later
+ *    without forcing it now.
+ *  - A truth hierarchy decides which fact wins: user > sync > import > inferred.
+ *  - `source` is an OPEN string so new origins (scim, workday, csv, org_chart,
+ *    google, slack, …) need no schema change; `tier` is the closed precedence axis.
+ */
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Provenance
+// ---------------------------------------------------------------------------
+
+/**
+ * The precedence axis for a fact. Closed set, ordered highest-precedence first
+ * (see {@link FACT_SOURCE_TIER_PRECEDENCE}). The specific origin lives in the
+ * open `source` string; this enum is what comparison / "who wins" reasons over.
+ */
+export const FactSourceTierSchema = z.enum([
+  "user",
+  "sync",
+  "import",
+  "inferred",
+]);
+export type FactSourceTier = z.infer<typeof FactSourceTierSchema>;
+
+/**
+ * Truth hierarchy, highest precedence first. A writer at a lower tier must never
+ * supersede a fact recorded at a higher tier (e.g. an org-chart import must not
+ * overwrite a `user`-entered reporting edge).
+ */
+export const FACT_SOURCE_TIER_PRECEDENCE = [
+  "user",
+  "sync",
+  "import",
+  "inferred",
+] as const satisfies ReadonlyArray<FactSourceTier>;
+
+/**
+ * Provenance envelope attached to a structural fact (reporting edge, org unit,
+ * membership, home assignment). The live value of any fact is the
+ * highest-precedence, non-superseded record.
+ */
+export const FactProvenanceSchema = z.object({
+  /** Precedence axis used by the truth hierarchy. */
+  tier: FactSourceTierSchema,
+  /**
+   * Specific origin — OPEN set, e.g. `manual` | `org_chart` | `scim` | `hris` |
+   * `csv` | `google` | `slack`. New origins slot in without a schema change.
+   */
+  source: z.string().min(1),
+  /** Extractor/matcher certainty in [0,1]; `null` for human-entered facts. */
+  confidence: z.number().min(0).max(1).nullable(),
+  /**
+   * True once a human has corrected/confirmed the fact. A locked fact is sticky:
+   * lower-tier writers (imports, inference) must not supersede it.
+   */
+  locked: z.boolean(),
+  /**
+   * The fact this record supersedes (immutable correction history); `null`/absent
+   * for an original. Enables append+supersede without destructive updates.
+   */
+  supersedesFactId: z.string().uuid().nullable().optional(),
+});
+export type FactProvenance = z.infer<typeof FactProvenanceSchema>;
+
+// ---------------------------------------------------------------------------
+// HomeAssignment (separate from membership)
+// ---------------------------------------------------------------------------
+
+/**
+ * A person's single structural home unit — at most one per person per org.
+ *
+ * SEPARATE relation from `org_unit_memberships` (NOT a `kind`/role flag on a
+ * shared table): the cardinalities differ on purpose — exactly one home, many
+ * memberships — which is the tell that they are different concepts. A shared
+ * `Membership(kind='home'|'member')` would inevitably grow
+ * `acting-home`/`temporary-home`/`future-home` flags.
+ *
+ * Home is an INPUT to authority derivation, sets `department`/`org` scope, and
+ * filters chart inclusion. It is NOT authority by itself (see Principles above).
+ * Supersedes the legacy `users.primary_unit_id` pointer (ADR-BE-120).
+ */
+export const HomeAssignmentSchema = z.object({
+  personId: z.string().uuid(),
+  orgUnitId: z.string().uuid(),
+  /** Provenance of this home assignment. Optional on lightweight projections. */
+  provenance: FactProvenanceSchema.optional(),
+});
+export type HomeAssignment = z.infer<typeof HomeAssignmentSchema>;