spec: add truth-plane OpenAPI/AsyncAPI patch files

asyncapi.truth-plane.patch.yaml

@@ -0,0 +1,93 @@
+# Additive AsyncAPI patch fragment for the Truth Plane.
+# Merge this file into asyncapi.yaml at build time using @asyncapi/bundler.
+# All channels use Kafka with the same broker configuration as the base spec.
+
+channels:
+  srcos.v2.truth.events:
+    description: Events emitted when a TruthSurface is recorded or updated.
+    bindings:
+      kafka:
+        topic: srcos.v2.truth.events
+        partitions: 3
+        replicas: 3
+        topicConfiguration:
+          retention.ms: 2592000000
+          cleanup.policy: delete
+    publish:
+      operationId: publishTruthSurfaceEvent
+      summary: Publish a truth surface domain event
+      description: Publishes an event whenever a TruthSurface is upserted.
+      message:
+        name: TruthSurfaceEvent
+        title: Truth Surface Domain Event
+        summary: A change event for a TruthSurface.
+        description: |
+          The `eventType` in the payload envelope identifies the specific change:
+          - `TruthSurfaceUpserted` — a TruthSurface was created or updated
+        contentType: application/json
+        payload: { $ref: './schemas/EventEnvelope.json' }
+        bindings:
+          kafka:
+            key:
+              type: string
+              description: The `objectId` URN of the TruthSurface.
+
+  srcos.v2.delta.events:
+    description: Events emitted when a DeltaSurface is recorded.
+    bindings:
+      kafka:
+        topic: srcos.v2.delta.events
+        partitions: 3
+        replicas: 3
+        topicConfiguration:
+          retention.ms: 2592000000
+          cleanup.policy: delete
+    publish:
+      operationId: publishDeltaSurfaceEvent
+      summary: Publish a delta surface domain event
+      description: Publishes an event whenever a DeltaSurface is recorded.
+      message:
+        name: DeltaSurfaceEvent
+        title: Delta Surface Domain Event
+        summary: A record event for a DeltaSurface.
+        description: |
+          The `eventType` in the payload envelope is `DeltaSurfaceRecorded`.
+          The payload contains the full DeltaSurface object.
+        contentType: application/json
+        payload: { $ref: './schemas/EventEnvelope.json' }
+        bindings:
+          kafka:
+            key:
+              type: string
+              description: The `objectId` URN of the DeltaSurface.
+
+  srcos.v2.incident.events:
+    description: Events emitted when an incident lifecycle event (freeze/fork/kill) is recorded.
+    bindings:
+      kafka:
+        topic: srcos.v2.incident.events
+        partitions: 3
+        replicas: 3
+        topicConfiguration:
+          retention.ms: 2592000000
+          cleanup.policy: delete
+    publish:
+      operationId: publishIncidentEvent
+      summary: Publish an incident domain event
+      description: Publishes an event whenever an incident lifecycle event is recorded.
+      message:
+        name: IncidentEvent
+        title: Incident Domain Event
+        summary: A lifecycle event for an incident phase.
+        description: |
+          The `eventType` in the payload envelope identifies the specific change:
+          - `IncidentFreezeRecorded`
+          - `IncidentForkRecorded`
+          - `IncidentKillRecorded`
+        contentType: application/json
+        payload: { $ref: './schemas/EventEnvelope.json' }
+        bindings:
+          kafka:
+            key:
+              type: string
+              description: The `objectId` URN of the incident event.

openapi.truth-plane.patch.yaml

@@ -0,0 +1,77 @@
+# Additive OpenAPI patch fragment for the Truth Plane (truth surfaces + delta surfaces + incident events).
+# Merge this file into openapi.yaml at build time.
+# All operations require bearerAuth (inherited from the base spec security requirement).
+
+tags:
+  - name: Truth Plane
+    description: Signed truth surfaces, delta surfaces, and incident lifecycle events
+
+paths:
+  /v2/truth/surfaces:
+    post:
+      operationId: upsertTruthSurface
+      summary: Upsert a TruthSurface
+      description: Creates or updates a signed TruthSurface emitted by a plane (system/user/agent/witness). Idempotent on `id`.
+      tags: [Truth Plane]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: './schemas/TruthSurface.json' }
+      responses:
+        '200':
+          description: TruthSurface created or updated successfully.
+        '400':
+          description: Request body is malformed JSON.
+        '401':
+          description: Missing or invalid authentication token.
+        '403':
+          description: Authenticated subject is not permitted to upsert truth surfaces.
+        '422':
+          description: Request body is valid JSON but fails schema validation.
+
+  /v2/truth/deltas:
+    post:
+      operationId: recordDeltaSurface
+      summary: Record a DeltaSurface
+      description: Records a signed DeltaSurface comparing two TruthSurfaces. Idempotent on `id`.
+      tags: [Truth Plane]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: './schemas/DeltaSurface.json' }
+      responses:
+        '200':
+          description: DeltaSurface recorded successfully.
+        '400':
+          description: Request body is malformed JSON.
+        '401':
+          description: Missing or invalid authentication token.
+        '403':
+          description: Authenticated subject is not permitted to record delta surfaces.
+        '422':
+          description: Request body is valid JSON but fails schema validation.
+
+  /v2/incidents:
+    post:
+      operationId: recordIncidentEvent
+      summary: Record an IncidentEvent
+      description: Records an incident lifecycle event (freeze/fork/kill) with evidence refs. Idempotent on `event_id`.
+      tags: [Truth Plane]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: './schemas/control-plane/incident-events.schema.json' }
+      responses:
+        '200':
+          description: IncidentEvent recorded successfully.
+        '400':
+          description: Request body is malformed JSON.
+        '401':
+          description: Missing or invalid authentication token.
+        '403':
+          description: Authenticated subject is not permitted to record incident events.
+        '422':
+          description: Request body is valid JSON but fails schema validation.