feat: implement AsyncAPI generation script and specs (#1317)

* feat: add AsyncAPI 3.0.0 generation script and specs

Add gen-asyncapi.sh that reads the Kafka topic registry (topics.yaml)
and proto event definitions to produce one AsyncAPI 3.0.0 YAML file per
BIAN service domain. The script extracts schema properties from proto
message definitions, infers partition keys as Kafka message binding keys,
and correctly excludes deprecated topics.

Generated specs cover all 9 service domains: audit, current-account,
financial-accounting, internal-account, market-information, party,
payment-order, position-keeping, and reconciliation.

Add `make asyncapi` target to Makefile.

* fix: address review feedback on gen-asyncapi.sh

Add python3 dependency check alongside yq check. Add payment_order_id
to the describe_partition_key case statement for human-readable Kafka
key descriptions. Regenerate payment-order.yaml with updated descriptions.

* fix: emit warning for unresolved proto messages instead of silent fallback

When a proto message cannot be resolved, the script now emits a warning
to stderr rather than silently writing placeholder schemas. This makes
source-of-truth drift visible in CI output while still generating
structurally valid YAML for partial specs.

* fix: preserve repeated-field element types and warn on parse failures

Capture element type from proto repeated fields so array schemas emit
the correct items type (integer, number, boolean) instead of always
defaulting to string. Also emit a warning to stderr when field JSON
parsing fails instead of silently falling back to placeholder schemas.

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

Makefile

@@ -32,7 +32,7 @@ GOMOD=$(GOCMD) mod
 GOGET=$(GOCMD) get
 GOFMT=$(GOCMD) fmt
 
-.PHONY: all help build seed-dev seed-dev-build test lint clean proto proto-v1 proto-v2 proto-openapi proto-lint proto-breaking proto-descriptors docker deploy-local fmt tidy deps coverage install proto-validate proto-deps-update proto-deps-graph proto-plugins-info validate-tilt validate-semconv validate-sagas proto-jsonschema validate-manifest-jsonschema validate-manifests control-plane-ci test-control-plane migrate-diff-all migrate-diff-current migrate-diff-position migrate-apply-all migrate-status-all migrate-lint-all migrate-hash-all migrate-apply-orgs migrate-status-orgs docs generate-saga-docs swagger-split swagger-ui dev-up dev-down dev-clean
+.PHONY: all help build seed-dev seed-dev-build test lint clean proto proto-v1 proto-v2 proto-openapi proto-lint proto-breaking proto-descriptors docker deploy-local fmt tidy deps coverage install proto-validate proto-deps-update proto-deps-graph proto-plugins-info validate-tilt validate-semconv validate-sagas proto-jsonschema validate-manifest-jsonschema validate-manifests control-plane-ci test-control-plane migrate-diff-all migrate-diff-current migrate-diff-position migrate-apply-all migrate-status-all migrate-lint-all migrate-hash-all migrate-apply-orgs migrate-status-orgs docs generate-saga-docs swagger-split swagger-ui dev-up dev-down dev-clean asyncapi
 
 # Default target
 all: help
@@ -490,6 +490,12 @@ generate-saga-docs:
 	@go run tools/saga-doc-gen/main.go tools/saga-doc-gen/generator.go -schema-dir=shared/pkg/saga/schema -output-dir=docs
 	@echo "Documentation generated successfully"
 
+## asyncapi: Generate AsyncAPI 3.0.0 specs from topic registry and proto definitions
+asyncapi:
+	@echo "Generating AsyncAPI specs..."
+	@./scripts/gen-asyncapi.sh
+	@echo "AsyncAPI specs generated in api/asyncapi/"
+
 ## validate-manifests: Validate example manifests against protobuf schema, CEL, and Starlark
 validate-manifests:
 	@echo "Validating example manifests..."

api/asyncapi/audit.yaml

@@ -0,0 +1,58 @@
+asyncapi: 3.0.0
+info:
+  title: "Audit Events"
+  version: 1.0.0
+  description: "Audit trail events for compliance and observability"
+servers:
+  kafka:
+    host: kafka:9092
+    protocol: kafka
+channels:
+  audit.events.v1:
+    address: "audit.events.v1"
+    description: "Audit events for all service operations"
+    messages:
+      AuditEvent:
+        $ref: '#/components/messages/AuditEvent'
+  audit.events.v1.dlq:
+    address: "audit.events.v1.dlq"
+    description: "Dead letter queue for audit events that could not be processed"
+operations:
+  publishEvents:
+    action: send
+    channel:
+      $ref: '#/channels/audit.events.v1'
+  publishEventsDlq:
+    action: send
+    channel:
+      $ref: '#/channels/audit.events.v1.dlq'
+components:
+  messages:
+    AuditEvent:
+      name: "AuditEvent"
+      title: "AuditEvent"
+      description: "Audit events for all service operations"
+      contentType: application/protobuf
+      headers:
+        type: object
+        properties:
+          event_type:
+            type: string
+            description: Logical event type identifier
+          correlation_id:
+            type: string
+            format: uuid
+            description: Links related events across services
+          tenant_id:
+            type: string
+            description: Tenant identifier for multi-tenant isolation
+      payload:
+        $ref: '#/components/schemas/AuditEvent'
+  schemas:
+    AuditEvent:
+      type: object
+      description: "Derived from protobuf message meridian.events.v1.AuditEvent"
+      properties:
+        event_type:
+          type: string
+          description: "Proto definition not yet available in api/proto/meridian/events/v1/"

api/asyncapi/current-account.yaml

@@ -0,0 +1,248 @@
+asyncapi: 3.0.0
+info:
+  title: "Current Account Events"
+  version: 1.0.0
+  description: "Account lifecycle and withdrawal events for current (demand deposit) accounts"
+servers:
+  kafka:
+    host: kafka:9092
+    protocol: kafka
+channels:
+  current-account.account-frozen.v1:
+    address: "current-account.account-frozen.v1"
+    description: "Published when an account is frozen (no debits or credits permitted)"
+    messages:
+      AccountFrozenEvent:
+        $ref: '#/components/messages/AccountFrozenEvent'
+  current-account.account-unfrozen.v1:
+    address: "current-account.account-unfrozen.v1"
+    description: "Published when a previously frozen account is unfrozen"
+    messages:
+      AccountUnfrozenEvent:
+        $ref: '#/components/messages/AccountUnfrozenEvent'
+  current-account.account-closed.v1:
+    address: "current-account.account-closed.v1"
+    description: "Published when an account is permanently closed"
+    messages:
+      AccountClosedEvent:
+        $ref: '#/components/messages/AccountClosedEvent'
+  current-account.withdrawal-status.v1:
+    address: "current-account.withdrawal-status.v1"
+    description: "Published when a withdrawal status changes (initiated, completed, failed, reversed)"
+    messages:
+      WithdrawalStatusUpdated:
+        $ref: '#/components/messages/WithdrawalStatusUpdated'
+operations:
+  publishAccountFrozen:
+    action: send
+    channel:
+      $ref: '#/channels/current-account.account-frozen.v1'
+  publishAccountUnfrozen:
+    action: send
+    channel:
+      $ref: '#/channels/current-account.account-unfrozen.v1'
+  publishAccountClosed:
+    action: send
+    channel:
+      $ref: '#/channels/current-account.account-closed.v1'
+  publishWithdrawalStatus:
+    action: send
+    channel:
+      $ref: '#/channels/current-account.withdrawal-status.v1'
+components:
+  messages:
+    AccountFrozenEvent:
+      name: "AccountFrozenEvent"
+      title: "AccountFrozenEvent"
+      description: "Published when an account is frozen (no debits or credits permitted)"
+      contentType: application/protobuf
+      bindings:
+        kafka:
+          key:
+            type: string
+            description: "Account ID"
+      headers:
+        type: object
+        properties:
+          event_type:
+            type: string
+            description: Logical event type identifier
+          correlation_id:
+            type: string
+            format: uuid
+            description: Links related events across services
+          tenant_id:
+            type: string
+            description: Tenant identifier for multi-tenant isolation
+      payload:
+        $ref: '#/components/schemas/AccountFrozenEvent'
+    AccountUnfrozenEvent:
+      name: "AccountUnfrozenEvent"
+      title: "AccountUnfrozenEvent"
+      description: "Published when a previously frozen account is unfrozen"
+      contentType: application/protobuf
+      bindings:
+        kafka:
+          key:
+            type: string
+            description: "Account ID"
+      headers:
+        type: object
+        properties:
+          event_type:
+            type: string
+            description: Logical event type identifier
+          correlation_id:
+            type: string
+            format: uuid
+            description: Links related events across services
+          tenant_id:
+            type: string
+            description: Tenant identifier for multi-tenant isolation
+      payload:
+        $ref: '#/components/schemas/AccountUnfrozenEvent'
+    AccountClosedEvent:
+      name: "AccountClosedEvent"
+      title: "AccountClosedEvent"
+      description: "Published when an account is permanently closed"
+      contentType: application/protobuf
+      bindings:
+        kafka:
+          key:
+            type: string
+            description: "Account ID"
+      headers:
+        type: object
+        properties:
+          event_type:
+            type: string
+            description: Logical event type identifier
+          correlation_id:
+            type: string
+            format: uuid
+            description: Links related events across services
+          tenant_id:
+            type: string
+            description: Tenant identifier for multi-tenant isolation
+      payload:
+        $ref: '#/components/schemas/AccountClosedEvent'
+    WithdrawalStatusUpdated:
+      name: "WithdrawalStatusUpdated"
+      title: "WithdrawalStatusUpdated"
+      description: "Published when a withdrawal status changes (initiated, completed, failed, reversed)"
+      contentType: application/protobuf
+      bindings:
+        kafka:
+          key:
+            type: string
+            description: "Withdrawal ID"
+      headers:
+        type: object
+        properties:
+          event_type:
+            type: string
+            description: Logical event type identifier
+          correlation_id:
+            type: string
+            format: uuid
+            description: Links related events across services
+          tenant_id:
+            type: string
+            description: Tenant identifier for multi-tenant isolation
+      payload:
+        $ref: '#/components/schemas/WithdrawalStatusUpdated'
+  schemas:
+    AccountFrozenEvent:
+      type: object
+      description: "Derived from protobuf message meridian.events.v1.AccountFrozenEvent"
+      properties:
+        event_id:
+          type: string
+        account_id:
+          type: string
+        reason:
+          type: string
+        frozen_at:
+          type: string
+        frozen_by:
+          type: string
+        correlation_id:
+          type: string
+        causation_id:
+          type: string
+        timestamp:
+          type: string
+        version:
+          type: integer
+        idempotency_key:
+          type: string
+    AccountUnfrozenEvent:
+      type: object
+      description: "Derived from protobuf message meridian.events.v1.AccountUnfrozenEvent"
+      properties:
+        event_id:
+          type: string
+        account_id:
+          type: string
+        unfrozen_at:
+          type: string
+        unfrozen_by:
+          type: string
+        correlation_id:
+          type: string
+        causation_id:
+          type: string
+        timestamp:
+          type: string
+        version:
+          type: integer
+        idempotency_key:
+          type: string
+    AccountClosedEvent:
+      type: object
+      description: "Derived from protobuf message meridian.events.v1.AccountClosedEvent"
+      properties:
+        event_id:
+          type: string
+        account_id:
+          type: string
+        closing_balance:
+          type: string
+        closure_reason:
+          type: string
+        closed_by:
+          type: string
+        closure_date:
+          type: string
+        correlation_id:
+          type: string
+        causation_id:
+          type: string
+        timestamp:
+          type: string
+        version:
+          type: integer
+        idempotency_key:
+          type: string
+    WithdrawalStatusUpdated:
+      type: object
+      description: "Derived from protobuf message meridian.events.v1.WithdrawalStatusUpdatedEvent"
+      properties:
+        event_id:
+          type: string
+        withdrawal_id:
+          type: string
+        account_id:
+          type: string
+        status:
+          type: string
+        correlation_id:
+          type: string
+        causation_id:
+          type: string
+        timestamp:
+          type: string
+        version:
+          type: integer
+        idempotency_key:
+          type: string

api/asyncapi/financial-accounting.yaml

@@ -0,0 +1,51 @@
+asyncapi: 3.0.0
+info:
+  title: "Financial Accounting Events"
+  version: 1.0.0
+  description: "Financial booking log control events"
+servers:
+  kafka:
+    host: kafka:9092
+    protocol: kafka
+channels:
+  financial-accounting.booking-log-controlled.v1:
+    address: "financial-accounting.booking-log-controlled.v1"
+    description: "Published when a booking log receives a control action (SUSPEND, RESUME, TERMINATE)"
+    messages:
+      BookingLogControlledEvent:
+        $ref: '#/components/messages/BookingLogControlledEvent'
+operations:
+  publishBookingLogControlled:
+    action: send
+    channel:
+      $ref: '#/channels/financial-accounting.booking-log-controlled.v1'
+components:
+  messages:
+    BookingLogControlledEvent:
+      name: "BookingLogControlledEvent"
+      title: "BookingLogControlledEvent"
+      description: "Published when a booking log receives a control action (SUSPEND, RESUME, TERMINATE)"
+      contentType: application/protobuf
+      headers:
+        type: object
+        properties:
+          event_type:
+            type: string
+            description: Logical event type identifier
+          correlation_id:
+            type: string
+            format: uuid
+            description: Links related events across services
+          tenant_id:
+            type: string
+            description: Tenant identifier for multi-tenant isolation
+      payload:
+        $ref: '#/components/schemas/BookingLogControlledEvent'
+  schemas:
+    BookingLogControlledEvent:
+      type: object
+      description: "Derived from protobuf message meridian.events.v1.BookingLogControlledEvent"
+      properties:
+        event_type:
+          type: string
+          description: "Proto definition not yet available in api/proto/meridian/events/v1/"