Refactor code structure for improved readability and maintainability

docs/api/concelier/concelier-lnm.yaml

@@ -1,8 +1,25 @@
 openapi: 3.1.0
 info:
   title: StellaOps Concelier – Link-Not-Merge Policy APIs
-  version: "0.1.0"
-  description: Fact-only advisory/linkset retrieval for Policy Engine consumers.
+  version: "1.0.0"
+  description: |
+    Fact-only advisory/linkset retrieval for Policy Engine consumers.
+
+    ## Philosophy
+    Link-Not-Merge (LNM) provides raw advisory data with full provenance:
+    - **Link**: Observations from multiple sources are linked via shared identifiers.
+    - **Not Merge**: Conflicting data is preserved rather than collapsed.
+    - **Surface, Don't Resolve**: Conflicts are clearly marked for consumers.
+
+    ## Authentication
+    All endpoints require the `X-Stella-Tenant` header for multi-tenant isolation.
+
+    ## Pagination
+    List endpoints support cursor-based pagination with `page` and `pageSize` parameters.
+    Maximum page size is 200 items.
+
+    ## Documentation
+    See `/docs/modules/concelier/api/` for detailed examples and conflict resolution strategies.
 servers:
   - url: /
     description: Relative base path (API Gateway rewrites in production).
@@ -44,6 +61,65 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/PagedLinksets'
+              examples:
+                single-linkset:
+                  summary: Single linkset result
+                  value:
+                    items:
+                      - advisoryId: "CVE-2021-23337"
+                        source: "nvd"
+                        purl: ["pkg:npm/lodash@4.17.20"]
+                        cpe: ["cpe:2.3:a:lodash:lodash:4.17.20:*:*:*:*:node.js:*:*"]
+                        summary: "Lodash Command Injection vulnerability"
+                        publishedAt: "2021-02-15T13:15:00Z"
+                        modifiedAt: "2024-08-04T19:16:00Z"
+                        severity: "high"
+                        provenance:
+                          ingestedAt: "2025-11-20T10:30:00Z"
+                          connectorId: "nvd-osv-connector"
+                          evidenceHash: "sha256:a1b2c3d4e5f6"
+                        conflicts: []
+                        cached: false
+                    page: 1
+                    pageSize: 50
+                    total: 1
+                with-conflicts:
+                  summary: Linkset with severity conflict
+                  value:
+                    items:
+                      - advisoryId: "CVE-2024-1234"
+                        source: "aggregated"
+                        purl: ["pkg:npm/example@1.0.0"]
+                        cpe: []
+                        severity: "high"
+                        provenance:
+                          ingestedAt: "2025-11-20T10:30:00Z"
+                          connectorId: "multi-source"
+                        conflicts:
+                          - field: "severity"
+                            reason: "severity-mismatch"
+                            observedValue: "critical"
+                            observedAt: "2025-11-18T08:00:00Z"
+                            evidenceHash: "sha256:conflict-hash"
+                        cached: false
+                    page: 1
+                    pageSize: 50
+                    total: 1
+        "400":
+          description: Invalid request parameters
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+              example:
+                type: "https://stellaops.io/errors/validation-failed"
+                title: "Validation Failed"
+                status: 400
+                detail: "The 'pageSize' parameter exceeds the maximum allowed value."
+                error:
+                  code: "ERR_PAGE_SIZE_EXCEEDED"
+                  message: "Page size must be between 1 and 200."
+                  target: "pageSize"
   /v1/lnm/linksets/{advisoryId}:
     get:
       summary: Get linkset by advisory ID
@@ -275,3 +351,63 @@ components:
         event: { type: string }
         at: { type: string, format: date-time }
         evidenceHash: { type: string }
+    ErrorEnvelope:
+      type: object
+      description: RFC 7807 Problem Details with StellaOps extensions
+      properties:
+        type:
+          type: string
+          format: uri
+          description: URI identifying the problem type
+        title:
+          type: string
+          description: Short, human-readable summary
+        status:
+          type: integer
+          description: HTTP status code
+        detail:
+          type: string
+          description: Specific explanation of the problem
+        instance:
+          type: string
+          format: uri
+          description: URI of the specific occurrence
+        traceId:
+          type: string
+          description: Distributed trace identifier
+        error:
+          $ref: '#/components/schemas/ErrorDetail'
+    ErrorDetail:
+      type: object
+      description: Machine-readable error information
+      properties:
+        code:
+          type: string
+          description: Machine-readable error code (e.g., ERR_VALIDATION_FAILED)
+        message:
+          type: string
+          description: Human-readable error message
+        target:
+          type: string
+          description: Field or resource that caused the error
+        metadata:
+          type: object
+          additionalProperties: true
+          description: Additional contextual data
+        innerErrors:
+          type: array
+          items:
+            $ref: '#/components/schemas/ValidationError'
+          description: Nested validation errors
+    ValidationError:
+      type: object
+      properties:
+        field:
+          type: string
+          description: Field path (e.g., "data.severity")
+        code:
+          type: string
+          description: Error code for this field
+        message:
+          type: string
+          description: Human-readable message