feat(api): add machine-readable HTTP and CDC contracts

contracts/README.md

@@ -0,0 +1,26 @@
+# Machine-readable contracts
+
+This directory contains release-facing interoperability contracts for behavior implemented on the protected mightyETL integration branch. These files are product interfaces, not aspirational roadmaps.
+
+## Authority model
+
+- `openapi/mightyetl.yaml` describes HTTP behavior implemented on protected `develop` only.
+- `asyncapi/mightyetl-cdc.yaml` describes the live PostgreSQL Debezium → Kafka publication boundary implemented on protected `develop` only.
+- An endpoint, header, lifecycle state, delivery guarantee, authentication mode, connector, or event transformation that exists only on an open pull request must not appear as protected product truth here.
+- Source annotations, controller/service behavior, migrations, and executable tests remain the runtime authority. `MachineReadableApiContractTest` binds the checked-in contracts to representative source declarations and fails when material source/contract identity drifts.
+
+## Versioning
+
+Contract `info.version` values identify the protected-development contract line, not an independently releasable semantic-version stream. A release must snapshot these contracts from the exact integrated release head and update them whenever a backward-incompatible public API or event contract changes.
+
+Backward-compatible additions may extend schemas or add operations only after the corresponding implementation is protected-integrated. Breaking changes require an explicit migration/deprecation plan, affected-client analysis, release notes, and the repository's normal independent review and release gates.
+
+## Failure and delivery claims
+
+The OpenAPI contract uses RFC 9457 `application/problem+json` only for ETL failures that the current `EtlApiProblemHandler` actually owns. Framework-owned, gateway-owned, and CDC text-error behavior are not silently normalized into that schema.
+
+The AsyncAPI contract deliberately describes replay-tolerant **at-least-once** CDC behavior. Protected `CdcService` currently forwards raw Debezium JSON to Kafka without waiting for acknowledgement before returning from its event handler. Stronger acknowledgement-before-source-progress behavior belongs to its separately reviewed implementation and must not be claimed here until protected integration proves it.
+
+## Validation
+
+Normal repository CI executes the Java contract tests. A future external OpenAPI/AsyncAPI validator may be added only when its version, supply-chain provenance, syntax support, and failure semantics are immutably governed; absence of such a tool is not grounds for weakening the current source-bound contract tests.

contracts/asyncapi/mightyetl-cdc.yaml

@@ -0,0 +1,65 @@
+asyncapi: 3.1.0
+info:
+  title: mightyETL protected CDC publication API
+  version: 0.1.0-develop
+  description: >-
+    Machine-readable description of the protected-develop PostgreSQL Debezium to Kafka publication boundary.
+    The live path forwards raw Debezium JSON and is replay-tolerant with at-least-once semantics; this contract
+    deliberately makes no end-to-end delivery-strength claim beyond that implemented behavior.
+defaultContentType: application/json
+servers:
+  kafkaBroker:
+    host: '{bootstrapServers}'
+    protocol: kafka
+    description: Deployment-provided Kafka bootstrap endpoint.
+    variables:
+      bootstrapServers:
+        default: localhost:9092
+        description: Kafka bootstrap host and port supplied by the deployment.
+channels:
+  debeziumChanges:
+    address: '{destination}'
+    title: Debezium change-event destination
+    description: >-
+      The actual Kafka destination is ChangeEvent.destination() supplied by Debezium. With the protected default
+      PostgreSQL connector configuration this derives from the configured topic prefix plus source table identity.
+    servers:
+      - $ref: '#/servers/kafkaBroker'
+    parameters:
+      destination:
+        description: Runtime Debezium destination/topic. Consumers must not assume a hard-coded table list.
+    messages:
+      rawDebeziumChange:
+        $ref: '#/components/messages/RawDebeziumChange'
+operations:
+  publishRawDebeziumChange:
+    action: send
+    title: Publish a raw Debezium change event
+    description: >-
+      mightyETL publishes the raw Debezium JSON value to Kafka. When Debezium supplies a key it is forwarded;
+      otherwise the key-less Kafka send form is used. The optional canonical mapper is validation/scaffolding and
+      does not replace the live publication payload.
+    channel:
+      $ref: '#/channels/debeziumChanges'
+    messages:
+      - $ref: '#/channels/debeziumChanges/messages/rawDebeziumChange'
+components:
+  messages:
+    RawDebeziumChange:
+      name: RawDebeziumChange
+      title: Raw Debezium JSON change event
+      summary: PostgreSQL CDC event forwarded without canonical payload transformation
+      contentType: application/json
+      description: >-
+        Payload compatibility follows the configured Debezium PostgreSQL connector JSON output. The current
+        protected implementation submits the Kafka send asynchronously and therefore documents replay-tolerant
+        at-least-once behavior rather than stronger broker-acknowledged source-progress semantics. PR #139 owns
+        the separate acknowledgement-before-progress repair.
+      headers:
+        type: object
+        additionalProperties: true
+        description: No application-specific Kafka header contract is asserted by protected mightyETL.
+      payload:
+        type: object
+        additionalProperties: true
+        description: Raw Debezium JSON object; schema evolves according to Debezium/source configuration.