Merge feature branch into main

Automated merge of feature branch into main

Author: Patel230

api/openapi.yaml

@@ -125,23 +125,15 @@ components:
         tool_calls:
           type: integer
 
-    Message:
+    GraphScope:
       type: object
       properties:
-        role:
+        tenant_id:
           type: string
-          enum: [user, assistant, tool]
-        content:
+        project_id:
+          type: string
+        repository_id:
           type: string
-        tool_use: {}
-        tool_results: {}
-
-    GraphScope:
-      type: object
-      properties:
-        tenant_id: {type: string}
-        project_id: {type: string}
-        repository_id: {type: string}
 
     GraphRef:
       type: object
@@ -150,91 +142,147 @@ components:
         kind:
           type: string
           enum: [system, knowledge, execution, policy, quality, operations]
-        id: {type: string}
+        id:
+          type: string
+
+    GraphArtifactRef:
+      type: object
+      required: [uri]
+      properties:
+        uri:
+          type: string
+        digest:
+          type: string
+        media_type:
+          type: string
 
     GraphProvenance:
       type: object
       required: [producer]
       properties:
-        producer: {type: string}
-        version: {type: string}
-        source_id: {type: string}
+        producer:
+          type: string
+        version:
+          type: string
+        source_id:
+          type: string
         evidence:
           type: array
           items:
-            type: object
-            required: [uri]
-            properties:
-              uri: {type: string}
-              digest: {type: string}
-              media_type: {type: string}
+            $ref: "#/components/schemas/GraphArtifactRef"
 
     GraphNode:
       type: object
       required: [id, kind, created_at, provenance]
       properties:
-        id: {type: string}
+        id:
+          type: string
         kind:
           type: string
           enum: [system, knowledge, execution, policy, quality, operations]
-        scope: {$ref: "#/components/schemas/GraphScope"}
-        created_at: {type: string, format: date-time}
-        effective_at: {type: string, format: date-time}
-        provenance: {$ref: "#/components/schemas/GraphProvenance"}
+        scope:
+          $ref: "#/components/schemas/GraphScope"
+        created_at:
+          type: string
+          format: date-time
+        effective_at:
+          type: string
+          format: date-time
+        provenance:
+          $ref: "#/components/schemas/GraphProvenance"
         attributes:
           type: object
-          additionalProperties: {type: string}
+          additionalProperties:
+            type: string
 
     GraphEdge:
       type: object
       required: [id, kind, from, to, created_at, provenance]
       properties:
-        id: {type: string}
+        id:
+          type: string
         kind:
           type: string
           enum: [contains, depends_on, references, produced, governed_by, validated_by]
-        from: {$ref: "#/components/schemas/GraphRef"}
-        to: {$ref: "#/components/schemas/GraphRef"}
-        scope: {$ref: "#/components/schemas/GraphScope"}
-        created_at: {type: string, format: date-time}
-        effective_at: {type: string, format: date-time}
-        provenance: {$ref: "#/components/schemas/GraphProvenance"}
+        from:
+          $ref: "#/components/schemas/GraphRef"
+        to:
+          $ref: "#/components/schemas/GraphRef"
+        scope:
+          $ref: "#/components/schemas/GraphScope"
+        created_at:
+          type: string
+          format: date-time
+        effective_at:
+          type: string
+          format: date-time
+        provenance:
+          $ref: "#/components/schemas/GraphProvenance"
         attributes:
           type: object
-          additionalProperties: {type: string}
+          additionalProperties:
+            type: string
 
     GraphEvent:
       type: object
       required: [id, type, subject, occurred_at, provenance]
       properties:
-        id: {type: string}
+        id:
+          type: string
         type:
           type: string
           enum: [created, updated, transitioned, observed, deleted]
-        subject: {$ref: "#/components/schemas/GraphRef"}
-        scope: {$ref: "#/components/schemas/GraphScope"}
-        occurred_at: {type: string, format: date-time}
-        correlation_id: {type: string}
-        causation_id: {type: string}
-        idempotency_key: {type: string}
-        provenance: {$ref: "#/components/schemas/GraphProvenance"}
+        subject:
+          $ref: "#/components/schemas/GraphRef"
+        scope:
+          $ref: "#/components/schemas/GraphScope"
+        occurred_at:
+          type: string
+          format: date-time
+        correlation_id:
+          type: string
+        causation_id:
+          type: string
+        idempotency_key:
+          type: string
+        provenance:
+          $ref: "#/components/schemas/GraphProvenance"
 
     ExecutionGraph:
       type: object
       required: [schema_version, generated_at, scope, nodes, edges, events]
       properties:
-        schema_version: {type: string, enum: [hawk.graph/v1]}
-        generated_at: {type: string, format: date-time}
-        scope: {$ref: "#/components/schemas/GraphScope"}
+        schema_version:
+          type: string
+          enum: [hawk.graph/v1]
+        generated_at:
+          type: string
+          format: date-time
+        scope:
+          $ref: "#/components/schemas/GraphScope"
         nodes:
           type: array
-          items: {$ref: "#/components/schemas/GraphNode"}
+          items:
+            $ref: "#/components/schemas/GraphNode"
         edges:
           type: array
-          items: {$ref: "#/components/schemas/GraphEdge"}
+          items:
+            $ref: "#/components/schemas/GraphEdge"
         events:
           type: array
-          items: {$ref: "#/components/schemas/GraphEvent"}
+          items:
+            $ref: "#/components/schemas/GraphEvent"
+
+    Message:
+      type: object
+      properties:
+        role:
+          type: string
+          enum: [user, assistant, tool]
+        content:
+          type: string
+        tool_use: {}
+        tool_results: {}
 
     PaginatedMessages:
       type: object
@@ -564,48 +612,67 @@ paths:
     get:
       tags: [graphs]
       summary: Project a persisted session as a portable execution graph
+      description: |
+        Returns Hawk's privacy-safe, read-only `hawk.graph/v1` projection.
+        Prompt text, tool arguments, tool output, and verification details are
+        excluded. Explicit Trace checkpoint IDs are additive to authoritative
+        Trace session correlation performed by Hawk.
       parameters:
         - name: id
           in: path
           required: true
-          schema: {type: string, maxLength: 128, pattern: '^[A-Za-z0-9._-]+$'}
+          schema:
+            type: string
+            maxLength: 128
+            pattern: '^[A-Za-z0-9._-]+$'
         - name: repository
           in: query
-          schema: {type: string, maxLength: 256}
+          description: Optional repository scope override.
+          schema:
+            type: string
+            maxLength: 256
         - name: trace_checkpoint
           in: query
+          description: Optional 12-character lowercase hexadecimal Trace checkpoint ID. May be repeated up to 64 times.
           schema:
             type: array
             maxItems: 64
-            items: {type: string, pattern: '^[0-9a-f]{12}$'}
+            items:
+              type: string
+              pattern: '^[0-9a-f]{12}$'
           style: form
           explode: true
       responses:
         "200":
           description: Portable execution graph
           content:
             application/json:
-              schema: {$ref: "#/components/schemas/ExecutionGraph"}
+              schema:
+                $ref: "#/components/schemas/ExecutionGraph"
         "400":
-          description: Invalid graph request
+          description: Invalid session, repository, or checkpoint input
           content:
             application/json:
-              schema: {$ref: "#/components/schemas/Error"}
+              schema:
+                $ref: "#/components/schemas/Error"
         "401":
           description: Unauthorized
           content:
             application/json:
-              schema: {$ref: "#/components/schemas/Error"}
+              schema:
+                $ref: "#/components/schemas/Error"
         "404":
           description: Session not found
           content:
             application/json:
-              schema: {$ref: "#/components/schemas/Error"}
+              schema:
+                $ref: "#/components/schemas/Error"
         "503":
-          description: Graph projection unavailable
+          description: Graph projection is not configured
           content:
             application/json:
-              schema: {$ref: "#/components/schemas/Error"}
+              schema:
+                $ref: "#/components/schemas/Error"
 
   /v1/stats:
     get: