diff --git a/asyncapi.truth-plane.patch.yaml b/asyncapi.truth-plane.patch.yaml new file mode 100644 index 0000000..2d30adf --- /dev/null +++ b/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. diff --git a/openapi.truth-plane.patch.yaml b/openapi.truth-plane.patch.yaml new file mode 100644 index 0000000..bbc7889 --- /dev/null +++ b/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.