session start works

specs/001-people-tend-to/contracts/openapi.yaml

@@ -0,0 +1,90 @@
+openapi: 3.0.0
+info:
+  title: Anonymous Desire Aggregator API
+  version: 2.0.0
+  description: API for facilitating real-time, private, anonymous decision-making sessions.
+
+paths:
+  /sessions:
+    post:
+      summary: Get a new unique session ID
+      operationId: createSession
+      responses:
+        '201':
+          description: Session ID created successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  sessionId:
+                    type: string
+                    format: uuid
+                    description: The unique ID for the session. Clients will use this to join the WebSocket channel.
+
+  /sessions/{sessionId}/analyze:
+    post:
+      summary: Trigger the semantic analysis for a session
+      operationId: triggerAnalysis
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                allDesires:
+                  type: array
+                  description: A complete list of all desire sets from all participants, collected by the client.
+                  items:
+                    type: object
+                    properties:
+                      wants:
+                        type: array
+                        items:
+                          type: string
+                      accepts:
+                        type: array
+                        items:
+                          type: string
+                      noGoes:
+                        type: array
+                        items:
+                          type: string
+      responses:
+        '202':
+          description: Analysis has been successfully triggered. Results will be broadcast over the WebSocket.
+        '404':
+          description: Session not found.
+
+# WebSocket Protocol (/sessions/{sessionId})
+# The primary communication for this application is via WebSockets. The backend acts as a message relay and orchestrator.
+#
+# Client-to-Server Messages:
+#
+# - type: 'SHARE_STATE'
+#   payload: { session: Session } # Client sends its entire session object to sync with others.
+#
+# - type: 'SUBMIT_DESIRES'
+#   payload: { desireSet: DesireSet } # A single user submits their desires.
+#
+# Server-to-Client Messages:
+#
+# - type: 'USER_JOINED'
+#   payload: { participantId: string }
+#
+# - type: 'STATE_UPDATE'
+#   payload: { session: Session } # Broadcasts the latest session state to all clients.
+#
+# - type: 'ANALYSIS_COMPLETE'
+#   payload: { decision: Decision } # Broadcasts the final results.
+#
+# - type: 'SESSION_LOCKED'
+#   payload: {}