docs: update BIAN references from v13 to v14 (#1299)

Author: bjcoombs

api/proto/meridian/market_information/v1/market_information.proto

@@ -327,7 +327,7 @@ message ObservationRecorded {
 // ========================================
 
 // MarketInformationService provides operations for managing market data sets,
-// observations, and data sources following BIAN v13.0 Market Information Management.
+// observations, and data sources following BIAN v14.0 Market Information Management.
 service MarketInformationService {
   // ----------------------------------------
   // Data Set Operations

docs/adr/0002-microservices-per-bian-domain.md

@@ -121,7 +121,7 @@ Core domains (FinancialAccounting, PositionKeeping) in monolith, customer-facing
 ## Links
 
 * [BIAN Service Landscape](https://bian.org/servicelandscape/)
-* [BIAN Semantic APIs](../../../bian/bian-public-main/release13.0.0/semantic-apis/)
+* [BIAN Semantic APIs](../../../bian/bian-public-main/release14.0.0/semantic-apis/)
 * [GitHub Issue #1: Infrastructure](https://github.com/meridianhub/meridian/issues/1)
 * [GitHub Issue #3: Platform Services](https://github.com/meridianhub/meridian/issues/3)
 

docs/adr/0004-event-schema-evolution.md

@@ -26,6 +26,8 @@ Supersedes initial decision to use Confluent Schema Registry.
 
 Amended: 2025-11-19 - Added event topic naming convention, outbox pattern, and idempotency pattern
 
+Amended: 2026-02-28 - Added BIAN v14 AsyncAPI specification awareness
+
 ## Context
 
 Meridian uses Apache Kafka for internal coordination between BIAN service domains. Events represent domain state
@@ -382,7 +384,7 @@ fields handle 90% of evolution needs. New event types handle the remaining 10% (
 - [ADR-0006: Schema Management with Adapters](./0006-schema-management-adapters.md)
 - [Protocol Buffers Language Guide](https://protobuf.dev/programming-guides/proto3/)
 - [buf CLI Documentation](https://buf.build/docs/)
-- [BIAN Service Landscape 13.0.0](https://bian.org/servicelandscape-13-0-0/)
+- [BIAN Service Landscape 14.0.0](https://bian.org/servicelandscape-14-0-0/)
 - [BIAN Semantic APIs](https://bian.org/semantic-apis/)
 
 ## Notes
@@ -1034,3 +1036,55 @@ func TestIdempotency(t *testing.T) {
 - [Event-Driven Architecture: Idempotent Consumers](../architecture/event-driven-architecture.md#idempotent-consumers)
 - [Outbox Pattern Amendment](#amendment-outbox-pattern-for-reliable-event-publishing-2025-11-19)
 - [CurrentAccount API Contract: Idempotency](../architecture/api-contracts/current-account-contract.md#idempotency)
+
+---
+
+## Amendment: BIAN v14 AsyncAPI Specification Awareness (2026-02-28)
+
+### Context
+
+BIAN v14.0.0 introduces formal [AsyncAPI 3.0.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0) specifications for all 259 service domains. This is the first time BIAN has provided machine-readable event definitions alongside its existing OpenAPI (REST) specs. Each service domain now includes an AsyncAPI YAML defining channels with `Created` and `Updated` message patterns (e.g., `OutboundMessage/Created`, `OutboundMessage/Updated`).
+
+**Example (BIAN AsyncAPI for CurrentAccount):**
+
+```yaml
+channels:
+  OutboundMessage/Created:
+    messages:
+      CurrentAccountOutbound:
+        payload:
+          $ref: '#/components/schemas/CurrentAccountOutbound'
+  OutboundMessage/Updated:
+    messages:
+      CurrentAccountOutbound:
+        payload:
+          $ref: '#/components/schemas/CurrentAccountOutbound'
+```
+
+**BIAN's approach is transport-agnostic**: channel names like `OutboundMessage/Created` are abstract and don't prescribe Kafka topic names, message broker topology, or serialization format.
+
+### Decision
+
+Acknowledge BIAN AsyncAPI specs as a **reference for payload structure** but continue using Meridian's existing topic naming convention (`<service>.<event-name>.<version>`) and protobuf serialization.
+
+**Rationale:**
+
+1. **Topic naming**: Meridian's dot-notation convention (`current-account.account-created.v1`) encodes service ownership directly in the topic name, which is operationally valuable for filtering, access control, and debugging. BIAN's `OutboundMessage/Created` channel naming is transport-agnostic and doesn't provide this operational benefit.
+
+2. **Payload alignment**: BIAN AsyncAPI schemas define JSON payloads matching the OpenAPI models. Meridian's Kafka events use protobuf serialization (per this ADR) with domain-specific event types rather than generic `ServiceDomainOutbound` wrappers. Our adapter layer (ADR-0005) handles the translation between BIAN's model structure and Meridian's internal event schemas.
+
+3. **Serialization**: BIAN AsyncAPI specs assume JSON payloads. Meridian uses protobuf for type safety, performance, and consistency with gRPC APIs (per this ADR's original decision). This remains the correct choice for internal event coordination.
+
+4. **Granularity**: BIAN defines two channels per domain (Created/Updated). Meridian uses fine-grained event types per BIAN behavior qualifier (AccountCreated, AccountSuspended, TransactionInitiated, etc.), which provides better consumer filtering and clearer domain semantics.
+
+### Future Considerations
+
+- **Payload structure review**: When implementing new service domains, cross-reference BIAN AsyncAPI payload schemas to ensure Meridian's protobuf event fields capture equivalent domain data.
+- **External integration**: If Meridian ever exposes event streams to external consumers, BIAN AsyncAPI specs could inform the external-facing contract while the internal protobuf events remain unchanged.
+- **BIAN evolution**: Monitor future BIAN releases for more prescriptive async patterns (e.g., CloudEvents envelope, transport-specific bindings) that may warrant revisiting this position.
+
+### References
+
+- [BIAN v14 AsyncAPI Specs](https://github.com/bian-official/public/tree/main/release14.0.0/semantic-apis/asyncapi)
+- [BIAN v14.0 Release Notes](https://bian.org/wp-content/uploads/2025/01/BIAN-v14.0-Release-Notes-v1.0.pdf)
+- [Topic Naming Amendment](#amendment-event-topic-naming-convention-2025-11-19)

docs/adr/0005-adapter-pattern-layer-translation.md

@@ -350,20 +350,20 @@ changes.
 
 ### Scenario: BIAN Adds New Behavior Qualifier
 
-#### BIAN 13.0 → 14.0 adds "Suspend" to Current Account
+#### BIAN 14.0 → 15.0 adds "Suspend" to Current Account
 
 #### Step 1: Update domain model (business logic)
 
 ```go
 // internal/domain/current_account.go
 
-// Updated for BIAN 14.0
+// Updated for BIAN 15.0
 type CurrentAccount struct {
     ID              uuid.UUID
     ControlRecordID string
     AccountStatus   AccountStatus
 
-    // New in BIAN 14.0
+    // New in BIAN 15.0
     SuspensionReason string
     SuspendedUntil   time.Time
     SuspendedBy      string
@@ -377,7 +377,7 @@ const (
     AccountStatusSuspended AccountStatus = "suspended"  // New
 )
 
-// New BIAN 14.0 behavior qualifier
+// New BIAN 15.0 behavior qualifier
 func (a *CurrentAccount) Suspend(reason string, until time.Time, by string) error {
     if a.AccountStatus != AccountStatusActive {
         return ErrInvalidStatusTransition
@@ -401,7 +401,7 @@ type CurrentAccountEntity struct {
     // ... existing fields
     AccountStatus    string     `gorm:"not null;size:50;index"`
 
-    // BIAN 14.0 fields (nullable for backward compatibility)
+    // BIAN 15.0 fields (nullable for backward compatibility)
     SuspensionReason *string    `gorm:"size:500"`
     SuspendedUntil   *time.Time `gorm:"index"`
     SuspendedBy      *string    `gorm:"size:255"`
@@ -414,7 +414,7 @@ func (r *CurrentAccountRepository) toEntity(d *domain.CurrentAccount) *CurrentAc
         AccountStatus: string(d.AccountStatus),
     }
 
-    // Map BIAN 14.0 fields (conditional based on status)
+    // Map BIAN 15.0 fields (conditional based on status)
     if d.AccountStatus == domain.AccountStatusSuspended {
         entity.SuspensionReason = &d.SuspensionReason
         entity.SuspendedUntil = &d.SuspendedUntil
@@ -431,7 +431,7 @@ func (r *CurrentAccountRepository) toDomain(e *CurrentAccountEntity) *domain.Cur
         AccountStatus: domain.AccountStatus(e.AccountStatus),
     }
 
-    // Map BIAN 14.0 fields if present
+    // Map BIAN 15.0 fields if present
     if e.SuspensionReason != nil {
         account.SuspensionReason = *e.SuspensionReason
     }
@@ -451,7 +451,7 @@ func (r *CurrentAccountRepository) toDomain(e *CurrentAccountEntity) *domain.Cur
 ```go
 // internal/adapters/events/current_account_publisher.go
 
-// New method for BIAN 14.0 behavior qualifier
+// New method for BIAN 15.0 behavior qualifier
 func (p *CurrentAccountPublisher) PublishSuspended(
     ctx context.Context,
     account *domain.CurrentAccount,
@@ -478,28 +478,28 @@ pace.
 #### 1. Independent layer evolution
 
 ```text
-Domain:      BIAN 14.0 (updated immediately)
+Domain:      BIAN 15.0 (updated immediately)
              ↓
-Persistence: BIAN 13.0 schema + new nullable columns (gradual migration)
+Persistence: BIAN 14.0 schema + new nullable columns (gradual migration)
              ↓
-Events:      New event type with BIAN 14.0 semantics (backward compatible)
+Events:      New event type with BIAN 15.0 semantics (backward compatible)
 ```
 
 #### 2. Backward compatibility
 
-Old consumers (BIAN 13.0) continue working:
+Old consumers (BIAN 14.0) continue working:
 
 * Database: Nullable columns don't break existing queries
 * Events: New event type on new topic (old consumers unaffected)
-* Domain: New behavior qualifiers only used by v14 clients
+* Domain: New behavior qualifiers only used by v15 clients
 
 #### 3. Gradual rollout
 
 ```text
-Week 1: Update CurrentAccount domain (BIAN 14.0)
+Week 1: Update CurrentAccount domain (BIAN 15.0)
 Week 2: Deploy database migration (add suspension columns)
 Week 3: Deploy new event type (account-suspended topic)
-Week 4+: Consuming services adopt BIAN 14.0 independently
+Week 4+: Consuming services adopt BIAN 15.0 independently
 ```
 
 **Without adapters:** Single BIAN upgrade would require coordinated deployment across all services, risking production

docs/adr/0012-lien-based-fund-reservation.md

@@ -46,7 +46,7 @@ to reserve funds without immediately debiting them.
 - **Overdraft prevention**: Must guarantee funds exist before initiating external payment
 - **Saga compensation**: Must be able to release funds if external payment fails
 - **Concurrent access**: Multiple payments from same account must work correctly
-- **BIAN alignment**: Follow BIAN v13 Current Account service domain patterns
+- **BIAN alignment**: Follow BIAN v14 Current Account service domain patterns
 - **Audit requirements**: Full traceability of fund reservations for regulatory compliance
 - **Performance**: Avoid blocking concurrent account operations during long-running sagas
 
@@ -369,7 +369,7 @@ if err := paymentGateway.Submit(order); err != nil {
 ## Links
 
 - [ADR-0005: Adapter Pattern for Layer Translation](0005-adapter-pattern-layer-translation.md)
-- [BIAN v13 Current Account Service Domain](https://bian.org/semantic-apis/current-account/) - Defines the
+- [BIAN v14 Current Account Service Domain](https://bian.org/semantic-apis/current-account/) - Defines the
   CurrentAccountFacility control record and associated behavior qualifiers
 - [Saga Pattern (Microsoft)](https://docs.microsoft.com/en-us/azure/architecture/reference-architectures/saga/saga)
 - [GitHub Issue #7: Payment Order Service](https://github.com/meridianhub/meridian/issues/7)

docs/adr/0014-financial-instrument-reference-data.md

@@ -29,7 +29,7 @@ manages those instrument definitions.
 
 ### BIAN Service Domain
 
-This ADR implements **BIAN Financial Instrument Reference Data Management** (v13.0.0):
+This ADR implements **BIAN Financial Instrument Reference Data Management** (v14.0.0):
 
 > "This Service Domain maintains a directory of financial instrument reference data"
 

docs/adr/0017-temporal-quality-ladder.md

@@ -1143,9 +1143,9 @@ func (e PositionEntry) GetAttributes(ctx context.Context, repo MeasurementReposi
 
 For settlement and reconciliation terms, see ADR-0018.
 
-## BIAN v13 Alignment
+## BIAN v14 Alignment
 
-This ADR's concepts map to BIAN (Banking Industry Architecture Network) v13 service domains:
+This ADR's concepts map to BIAN (Banking Industry Architecture Network) v14 service domains:
 
 | Meridian Concept | BIAN Service Domain | BIAN Entity | Notes |
 |-----------------|---------------------|-------------|-------|

docs/adr/0018-settlement-reconciliation.md

@@ -966,9 +966,9 @@ var (
 | **Variance** | Difference between settled quantity and current quantity for a position |
 | **Dispute** | Record created when new data arrives for a locked (finalized) position |
 
-## BIAN v13 Alignment
+## BIAN v14 Alignment
 
-This ADR's concepts map to BIAN (Banking Industry Architecture Network) v13 service domains:
+This ADR's concepts map to BIAN (Banking Industry Architecture Network) v14 service domains:
 
 | Meridian Concept | BIAN Service Domain | BIAN Entity | Notes |
 |-----------------|---------------------|-------------|-------|

docs/adr/0025-clearing-purpose-specialization.md

@@ -169,7 +169,7 @@ Create separate tables: `deposit_clearing_accounts`, `withdrawal_clearing_accoun
 * [ADR-0024: Internal Account Service](0024-internal-account-service.md)
 * [Internal Account README](../../services/internal-account/README.md)
 * [Proto Definitions](../../api/proto/meridian/internal_account/v1/internal_account.proto)
-* [BIAN v13.0 Internal Account Service Domain](https://bian.org/semantic-apis/internal-account/)
+* [BIAN Internal Account Service Domain](https://bian.org/semantic-apis/internal-account/)
 
 ## Notes
 

docs/architecture/api-contracts/current-account-contract.md

@@ -860,4 +860,4 @@ facility.CurrentBalance = mapBalancesToResponse(balances)
 - **ADR-0002**: Microservices Per BIAN Domain
 - **ADR-0005**: Adapter Pattern Layer Translation
 - **ADR-0023**: Balance Delegation to Position Keeping
-- **BIAN Reference**: Current Account Service Domain (Release 13.0)
+- **BIAN Reference**: Current Account Service Domain (Release 14.0)