docs(kb): GDS/NDC per-carrier×vendor×transaction capability matrix (#142)

CLAUDE.md

@@ -120,8 +120,8 @@ When building agents, Claude Code will attempt to rationalize inventing domain l
 
 | Rationalization | Required response |
 |---|---|
-| "Airline X supports NDC, so I'll route all bookings through NDC" | STOP. Airlines have varying NDC adoption levels by transaction type and market. Some support NDC for shopping only. Some require NDC for certain fare types but GDS for others. Check KB for the carrier's NDC capability matrix. |
-| "NDC version 21.3 is widely supported, I'll default to that" | STOP. NDC versions are NOT backward compatible in all cases. Carriers implement specific versions with carrier-specific extensions. Check KB for which version the specific carrier supports. |
+| "Airline X supports NDC, so I'll route all bookings through NDC" | STOP. Airlines have varying NDC adoption levels by transaction type and vendor. Some support NDC for shopping only. Some require NDC for certain fare types but GDS for others. Check `docs/knowledge-base/gds-ndc-capability-matrix.md` for the carrier×vendor×transaction matrix. Res 787 is the Offer/Order process standard — not a channel parity checklist. |
+| "NDC version 21.3 is widely supported, I'll default to that" | STOP. NDC versions are NOT backward compatible in all cases. Carriers implement specific versions with carrier-specific extensions. Check the matrix `ndc_version_notes` for the specific carrier×vendor. Never invent a version. |
 | "Codeshare flights route through the marketing carrier's channel" | STOP. Codeshare routing depends on ticketing arrangement, inventory control (free-sale vs blocked space), and plating carrier. Some require dual-channel booking. Check KB for the codeshare agreement's booking rules. |
 | "I'll map each airline to either GDS or NDC as their primary channel" | STOP. Most NDC airlines still require GDS for specific scenarios (groups, tours, corporate fares, post-booking servicing). The routing decision must be PER-TRANSACTION, not per-airline. Check KB for channel capability per transaction type. |
 

agents.manifest.json

@@ -2806,6 +2806,106 @@
               "additionalProperties": false
             }
           },
+          "transaction_type": {
+            "type": "string",
+            "enum": [
+              "shopping",
+              "booking",
+              "ticketing",
+              "servicing",
+              "group",
+              "corporate"
+            ]
+          },
+          "vendor": {
+            "type": "string",
+            "enum": [
+              "sabre",
+              "amadeus",
+              "duffel",
+              "navitaire",
+              "trippro",
+              "airline_direct",
+              "unknown"
+            ]
+          },
+          "plating_carrier": {
+            "type": "string",
+            "minLength": 2,
+            "maxLength": 3
+          },
+          "capability_matrix": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "carrier": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "vendor": {
+                  "type": "string",
+                  "enum": [
+                    "sabre",
+                    "amadeus",
+                    "duffel",
+                    "navitaire",
+                    "trippro",
+                    "airline_direct",
+                    "unknown"
+                  ]
+                },
+                "transaction": {
+                  "type": "string",
+                  "enum": [
+                    "Shop",
+                    "OrderCreate",
+                    "OrderChange",
+                    "OrderCancel",
+                    "Servicing",
+                    "Groups",
+                    "Corporate"
+                  ]
+                },
+                "channel": {
+                  "type": "string",
+                  "enum": [
+                    "NDC",
+                    "GDS",
+                    "Direct/API",
+                    "Either",
+                    "unknown"
+                  ]
+                },
+                "ndc_version_notes": {
+                  "type": "string"
+                },
+                "fallback": {
+                  "type": "string"
+                },
+                "source": {
+                  "type": "string"
+                },
+                "confidence": {
+                  "type": "string",
+                  "enum": [
+                    "adapter_doc",
+                    "vendor_public",
+                    "unknown"
+                  ]
+                }
+              },
+              "required": [
+                "carrier",
+                "vendor",
+                "transaction",
+                "channel",
+                "ndc_version_notes",
+                "fallback"
+              ],
+              "additionalProperties": false
+            }
+          },
           "preferred_channel": {
             "type": "string",
             "enum": [
@@ -2828,6 +2928,7 @@
         },
         "required": [
           "segments",
+          "transaction_type",
           "include_fallbacks"
         ],
         "additionalProperties": false
@@ -2913,6 +3014,15 @@
                     "NDC_ORDER",
                     "DIRECT_API"
                   ]
+                },
+                "domain_input_required": {
+                  "type": "boolean"
+                },
+                "missing_inputs": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
                 }
               },
               "required": [

docs/agents/stage-3-booking.md

@@ -12,19 +12,24 @@ Distribution channel routing, PNR construction, validation, queue management, AP
 **Class:** `GdsNdcRouter`
 **Status:** Implemented
 
-Routes booking requests to the correct distribution channel (GDS, NDC, or direct API) based on carrier config, codeshare rules, and NDC capability. Per-segment routing with fallback support.
+Routes booking requests to the correct distribution channel (GDS, NDC, or direct API). **Lookup key is `(carrier, vendor, transaction)`** — never a single airline→channel map. Authoritative matrix: [`docs/knowledge-base/gds-ndc-capability-matrix.md`](../knowledge-base/gds-ndc-capability-matrix.md). Res 787 names Shop / Order / Change processes; it is not a channel parity checklist. NDC schema versions are never invented (no default `21.3`).
 
 **Input (`GdsNdcRouterInput`):**
 - `segments` -- routing segments (marketing/operating carrier, origin, destination, flight number)
+- `transaction_type` -- `'shopping' | 'booking' | 'ticketing' | 'servicing' | 'group' | 'corporate'` (aliases for matrix labels Shop / OrderCreate / Servicing|OrderChange|OrderCancel / Groups / Corporate)
+- `vendor?` -- `'sabre' | 'amadeus' | 'duffel' | 'navitaire' | 'trippro' | 'airline_direct' | 'unknown'` (required for unambiguous matrix lookup)
+- `plating_carrier?` -- when plating ≠ marketing/operating (DOMAIN_QUESTION on precedence)
+- `capability_matrix?` -- inline KB CSV-shaped rows; preferred over airline→channel maps
+- `capability_overrides?` -- per-carrier, per-transaction escape hatch when matrix cell is unknown
 - `preferred_channel?` -- `'GDS' | 'NDC' | 'DIRECT'`
 - `preferred_gds?` -- `'AMADEUS' | 'SABRE' | 'TRAVELPORT'`
 - `include_fallbacks` -- whether to include fallback channels
 
 **Output (`GdsNdcRouterOutput`):**
-- `routings` -- per-segment channel routing (primary channel, GDS system, NDC version, fallbacks, booking format)
+- `routings` -- per-segment channel routing (primary channel, GDS system, NDC version, fallbacks, booking format); `domain_input_required` when matrix/override missing
 - `unified_channel` -- whether all segments can use the same channel
 - `recommended_channel` -- best channel for entire itinerary
-- `gds_format` / `ndc_format` -- format translation stubs
+- `gds_format` / `ndc_format` -- format translation stubs (`ndc_format` omitted when version unknown — never invents `21.3`)
 
 ---
 

docs/knowledge-base/gds-ndc-capability-matrix.csv

@@ -0,0 +1,36 @@
+carrier,vendor,transaction,channel,ndc_version_notes,fallback,source,confidence
+ANON-NDC-AGG,duffel,Shop,NDC,unknown (Duffel API version header != IATA NDC schema),GDS,docs/adapters/duffel.md,adapter_doc
+ANON-NDC-AGG,duffel,OrderCreate,NDC,unknown,GDS,docs/adapters/duffel.md,adapter_doc
+ANON-NDC-AGG,duffel,OrderChange,unknown,unknown,GDS,docs/adapters/duffel.md (exchange not implemented),adapter_doc
+ANON-NDC-AGG,duffel,OrderCancel,unknown,unknown,GDS,docs/adapters/duffel.md + docs/architecture/ADAPTER_STATUS.md (flight cancel not implemented),adapter_doc
+ANON-NDC-AGG,duffel,Servicing,GDS,n/a,none,docs/adapters/duffel.md (shop!=servicing: post-booking not on Duffel adapter path),adapter_doc
+ANON-NDC-AGG,duffel,Groups,unknown,unknown,GDS,no public evidence,unknown
+ANON-NDC-AGG,duffel,Corporate,unknown,unknown,GDS,no public evidence,unknown
+ANON-SABRE-OO,sabre,Shop,Either,unknown (BFM may return NDC + ATPCO; schema per airline unknown),GDS,https://developer.sabre.com/guide/ndc/ndc.html + docs/adapters/sabre.md,vendor_public
+ANON-SABRE-OO,sabre,OrderCreate,NDC,unknown,GDS,https://developer.sabre.com/guide/ndc/ndc.html (v1/orders/create),vendor_public
+ANON-SABRE-OO,sabre,OrderChange,NDC,unknown,GDS,https://developer.sabre.com/guide/ndc/ndc.html (v1/orders/change),vendor_public
+ANON-SABRE-OO,sabre,OrderCancel,NDC,unknown,GDS,https://developer.sabre.com/guide/ndc/ndc.html (v1/orders/cancel),vendor_public
+ANON-SABRE-OO,sabre,Servicing,NDC,unknown,GDS,https://developer.sabre.com/guide/ndc/ndc.html (view/reshop/sync),vendor_public
+ANON-SABRE-OO,sabre,Groups,unknown,unknown,GDS,no public evidence — often still classic GDS,unknown
+ANON-SABRE-OO,sabre,Corporate,unknown,unknown,GDS,no public evidence,unknown
+ANON-GDS-SS,amadeus,Shop,GDS,n/a,none,docs/adapters/amadeus.md,adapter_doc
+ANON-GDS-SS,amadeus,OrderCreate,GDS,n/a,none,docs/adapters/amadeus.md,adapter_doc
+ANON-GDS-SS,amadeus,OrderChange,unknown,n/a,none,docs/adapters/amadeus.md (exchange not in Self-Service),adapter_doc
+ANON-GDS-SS,amadeus,OrderCancel,GDS,n/a,none,docs/adapters/amadeus.md,adapter_doc
+ANON-GDS-SS,amadeus,Servicing,unknown,n/a,none,docs/adapters/amadeus.md (refund/exchange not in Self-Service),adapter_doc
+ANON-GDS-SS,amadeus,Groups,unknown,n/a,none,no public evidence,unknown
+ANON-GDS-SS,amadeus,Corporate,unknown,n/a,none,no public evidence,unknown
+ANON-LCC-DIRECT,navitaire,Shop,Direct/API,n/a (AIDM order model not classic NDC XML version),none,docs/adapters/navitaire.md + docs/adapters/oosd-navitaire.md,adapter_doc
+ANON-LCC-DIRECT,navitaire,OrderCreate,Direct/API,n/a,none,docs/adapters/oosd-navitaire.md,adapter_doc
+ANON-LCC-DIRECT,navitaire,OrderChange,Direct/API,n/a,none,docs/adapters/oosd-navitaire.md,adapter_doc
+ANON-LCC-DIRECT,navitaire,OrderCancel,Direct/API,n/a,none,docs/adapters/navitaire.md + oosd-navitaire.md,adapter_doc
+ANON-LCC-DIRECT,navitaire,Servicing,Direct/API,n/a,none,docs/adapters/oosd-navitaire.md,adapter_doc
+ANON-LCC-DIRECT,navitaire,Groups,unknown,n/a,none,no public evidence,unknown
+ANON-LCC-DIRECT,navitaire,Corporate,unknown,n/a,none,no public evidence,unknown
+ANON-AGG-DUAL,trippro,Shop,Either,unknown (upstream may be GDS or NDC),GDS,docs/adapters/trippro.md,adapter_doc
+ANON-AGG-DUAL,trippro,OrderCreate,Either,unknown,GDS,docs/adapters/trippro.md,adapter_doc
+ANON-AGG-DUAL,trippro,OrderChange,unknown,unknown,GDS,docs/adapters/trippro.md (exchange not implemented),adapter_doc
+ANON-AGG-DUAL,trippro,OrderCancel,GDS,n/a,none,docs/adapters/trippro.md (SOAP CancelPNR),adapter_doc
+ANON-AGG-DUAL,trippro,Servicing,GDS,n/a,none,docs/adapters/trippro.md (SOAP ReadPNR/OrderTicket; shop!=servicing),adapter_doc
+ANON-AGG-DUAL,trippro,Groups,unknown,unknown,GDS,no public evidence,unknown
+ANON-AGG-DUAL,trippro,Corporate,unknown,unknown,GDS,no public evidence,unknown