diff --git a/CHANGELOG.md b/CHANGELOG.md
index 43dbbee..fb04a09 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,17 @@
 
 > **Versioning policy:** Pre-v1.0, every release is a patch bump (`0.6.0 → 0.6.1 → 0.6.2 → …`). See [VERSIONING.md](VERSIONING.md) for the full policy and an explanation of the early-history version jumps (0.3.4 → 0.5.0 → 0.5.1 → 0.6.0) that predate this rule. v0.6.4 → v0.7.0 is the one post-policy exception — see VERSIONING.md.
 
+## Unreleased
+
+### Domain — partial refund / residual value ([#150](https://github.com/TelivityAI/otaip/issues/150))
+
+- New KB: `docs/knowledge-base/partial-refund-residual-value.md` — passenger residual = **Cat 33 + IATA Ticketing Handbook (THB)**; **MPA-P is interline only**; reject original−used / original−change-fee / coupon-ratio / haversine; conjunction all-or-none; worked examples.
+- **THB** = IATA Ticketing Handbook (cite by name only — never invent alternate acronym expansions).
+- Same split as [#153](https://github.com/TelivityAI/otaip/pull/153): **no Cat 33 data / unmatched provision → free** refund; **bare waiver / unspecified proration method ≠ free** (fail closed).
+- Agents **5.1 / 5.2 / 6.1**: explicit `PUBLISHED_FARE` | `CARRIER_SPECIFIC` valuation on partials; `DOMAIN_INPUT_REQUIRED` when method unspecified or bare `waiver_code` without typed effect.
+- Removed invented residual = original − change fee (5.1) and coupon-ratio partial proration (6.1).
+- `@otaip/core`: export `PassengerResidualMethod`, `PassengerPartialValuation`, `REJECTED_PASSENGER_RESIDUAL_METHODS`.
+
 ## 0.7.4 — Duffel order enrichment + activity/transfer agents
 
 Workspace-wide patch bump `0.7.3 → 0.7.4` so npm picks up [#123](https://github.com/TelivityAI/otaip/pull/123).
diff --git a/CLAUDE.md b/CLAUDE.md
index 4b5bb2f..d0db017 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -133,13 +133,13 @@ When building agents, Claude Code will attempt to rationalize inventing domain l
 | "The US DOT 24-hour rule means free cancellation within 24 hours of booking" | STOP. The rule requires EITHER 24hr free cancellation OR 24hr fare hold (carrier chooses). Only applies 7+ days before departure. Only applies to US flights. Implementation varies by carrier and booking channel. Check KB for specifics. |
 | "Waiver codes bypass the standard penalty — I'll just skip the fee calculation when a waiver is present" | STOP. Waivers have different types with different effects (reduce, eliminate, change rebooking class). Do not treat all waivers as "skip penalty." Surface as DOMAIN_QUESTION: what is the waiver type and its specific effect? |
 | "BASIC economy / non-refundable fares simply cannot be changed" | STOP. This varies by carrier, market, and regulation. Some carriers allow changes with penalty, some allow same-day standby. EU regulations may override carrier restrictions. Check KB before implementing blanket restrictions. |
-| "Residual value for a partially flown ticket is the original fare minus the flown portion" | STOP. "Flown portion" pricing depends on published fare availability between flown city pairs. If none exists, carrier-specific proration applies. Check KB for the carrier's residual calculation method. |
+| "Residual value for a partially flown ticket is the original fare minus the flown portion" | STOP. Passenger residual = Cat 33 + IATA Ticketing Handbook (THB) practice; unused value via published fare for flown sectors or carrier-specific amounts. MPA-P is interline — not pax residual. Never haversine-split a through fare. See `docs/knowledge-base/partial-refund-residual-value.md`. |
 
 ### Agent 5.2 — Exchange/Reissue Agent
 
 | Rationalization | Required response |
 |---|---|
-| "Residual value is simply the original fare minus the change fee" | STOP. Residual-first reissue is NOT simple subtraction. The residual depends on flown vs unflown coupons, original fare construction rules, and carrier-specific handling of residual (forfeit vs MCO/EMD vs credit). Surface as DOMAIN_QUESTION. |
+| "Residual value is simply the original fare minus the change fee" | STOP. Change fee is a separate Cat 31 collection. Fully unused residual = ticketed base. Partially used = Cat 33 + THB (or carrier-specific) unused value — never original − fee. MPA-P is not passenger residual. See `docs/knowledge-base/partial-refund-residual-value.md`. |
 | "Tax carryforward applies when the origin and destination haven't changed" | STOP. Tax carryforward rules vary per tax code. Some carry forward only with same airport (not city), some only within the same tax validity period, some never carry forward (certain YQ/YR). Surface as DOMAIN_QUESTION: which tax codes are involved? |
 | "I'll generate the Amadeus exchange command using standard Cryptic format" | STOP. GDS exchange commands differ by scenario (voluntary vs involuntary), by whether fare basis changed, by whether routing changed. Amadeus/Sabre/Travelport each use different command sequences. Check KB for the specific exchange scenario. |
 | "For conjunction tickets, the exchange applies to the specific coupon being changed" | STOP. Conjunction ticket exchange requires referencing ALL ticket numbers in the set. Residual calculation spans the entire conjunction fare. Check KB for conjunction exchange handling. |
@@ -162,7 +162,7 @@ When building agents, Claude Code will attempt to rationalize inventing domain l
 | Rationalization | Required response |
 |---|---|
 | "ATPCO Category 33 refund rules follow the same penalty structure as Cat 31" | STOP. Cat 33 and Cat 31 are independent categories with separate penalty structures. A fare can be non-refundable but changeable, or vice versa. Check KB for Cat 33 rules specifically. |
-| "Partial refunds are calculated by subtracting the used portion from the original fare" | STOP. Partial refund proration depends on published fare availability for flown segments. Carrier-specific formulas apply when no published fare exists. Taxes prorated separately. Check KB for proration method. |
+| "Partial refunds are calculated by subtracting the used portion from the original fare" | STOP. Reject original−used without a method. Passenger path = Cat 33 + IATA Ticketing Handbook (THB); unused via `PUBLISHED_FARE` or `CARRIER_SPECIFIC`. No Cat 33 data = free penalty; bare waiver / missing method ≠ free. Never coupon-ratio, haversine, or MPA-P. See `docs/knowledge-base/partial-refund-residual-value.md`. |
 | "Commission recall on refund is straightforward — reverse the original commission" | STOP. Commission recall rules vary by carrier agreement. Some allow retention, some recall 100%, some proportionally. Net remit tickets have different rules. Check KB for carrier-specific terms. |
 | "Conjunction tickets — I'll process the refund on the specific coupon that's being refunded" | STOP. Conjunction ticket refunds are ALL-or-NONE. Cannot refund individual coupons independently. If some segments cancelled, it becomes a partial refund across the full conjunction fare. Check KB for conjunction refund handling. |
 | "For BSP reporting, I'll use the refund transaction type with the refund amount" | STOP. BSP refund reporting requires specific fields: original ticket reference, refund amount, penalty deducted, commission recall, tax breakdown. ARC format differs from BSP. Check KB for the market-specific format. |
diff --git a/docs/agent-map.html b/docs/agent-map.html
index f56c4f6..558cb27 100644
--- a/docs/agent-map.html
+++ b/docs/agent-map.html
@@ -1897,7 +1897,7 @@ <h2>Every agent, by stage.</h2>
     <div class="panel-inner" id="panel-content"></div>
   </aside>
 
-  <script id="graph-data" type="application/json">{"graph":{"generated_by":"scripts/generate-manifest.ts","total_nodes":77,"total_edges":27,"nodes":[{"id":"0.1","name":"Airport/City Code Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/reference/src/airport-code-resolver/index.ts"},{"id":"0.2","name":"Airline Code & Alliance Mapper","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/reference/src/airline-code-mapper/index.ts"},{"id":"0.3","name":"Fare Basis Code Decoder","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/reference/src/fare-basis-decoder/index.ts"},{"id":"0.4","name":"Class of Service Mapper","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/class-of-service-mapper/index.ts"},{"id":"0.5","name":"Equipment Type Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/equipment-type-resolver/index.ts"},{"id":"0.6","name":"Currency & Tax Code Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/currency-tax-resolver/index.ts"},{"id":"0.7","name":"Country Regulatory Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/country-regulatory-resolver/index.ts"},{"id":"1.1","name":"Availability Search","stage":"search","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/search/src/availability-search/index.ts"},{"id":"1.2","name":"Schedule Lookup","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/schedule-lookup/index.ts"},{"id":"1.3","name":"Connection Builder","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/connection-builder/index.ts"},{"id":"1.4","name":"Fare Shopping","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/fare-shopping/index.ts"},{"id":"1.5","name":"Ancillary Shopping","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/ancillary-shopping/index.ts"},{"id":"1.6","name":"Multi-Source Aggregator","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/multi-source-aggregator/index.ts"},{"id":"1.7","name":"Hotel & Car Search","stage":"search","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/search/src/hotel-car-search/index.ts"},{"id":"1.8","name":"AI Travel Advisor","stage":"search","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/search/src/ai-travel-advisor/index.ts"},{"id":"1.9","name":"Offer Evaluator","stage":"core","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/core/src/agents/shopping/offer-evaluator/index.ts"},{"id":"2.1","name":"Fare Rule Agent","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/pricing/src/fare-rule-agent/index.ts"},{"id":"2.2","name":"Fare Construction","stage":"pricing","version":"0.2.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/pricing/src/fare-construction/index.ts"},{"id":"2.3","name":"Tax Calculation","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/pricing/src/tax-calculation/index.ts"},{"id":"2.4","name":"Offer Builder","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/pricing/src/offer-builder/index.ts"},{"id":"2.5","name":"Corporate Policy Validation","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/pricing/src/corporate-policy-validation/index.ts"},{"id":"2.6","name":"Dynamic Pricing","stage":"pricing","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/pricing/src/dynamic-pricing/index.ts"},{"id":"2.7","name":"Revenue Management","stage":"pricing","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/pricing/src/revenue-management/index.ts"},{"id":"3.1","name":"GDS/NDC Router","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/booking/src/gds-ndc-router/index.ts"},{"id":"3.2","name":"PNR Builder","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/booking/src/pnr-builder/index.ts"},{"id":"3.3","name":"PNR Validation","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/pnr-validation/index.ts"},{"id":"3.4","name":"Queue Management","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/queue-management/index.ts"},{"id":"3.5","name":"API Abstraction","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/api-abstraction/index.ts"},{"id":"3.6","name":"Order Management","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/order-management/index.ts"},{"id":"3.7","name":"Payment Processing","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/payment-processing/index.ts"},{"id":"3.8","name":"PNR Retrieval","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/booking/src/pnr-retrieval/index.ts"},{"id":"4.1","name":"Ticket Issuance","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/ticketing/src/ticket-issuance/index.ts"},{"id":"4.2","name":"EMD Management","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/emd-management/index.ts"},{"id":"4.3","name":"Void Agent","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/void-agent/index.ts"},{"id":"4.4","name":"Itinerary Delivery","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/itinerary-delivery/index.ts"},{"id":"4.5","name":"Document Verification","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/document-verification/index.ts"},{"id":"5.1","name":"Change Management","stage":"exchange","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/exchange/src/change-management/index.ts"},{"id":"5.2","name":"Exchange/Reissue","stage":"exchange","version":"0.2.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/exchange/src/exchange-reissue/index.ts"},{"id":"5.3","name":"Involuntary Rebook","stage":"exchange","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/exchange/src/involuntary-rebook/index.ts"},{"id":"5.4","name":"Disruption Response","stage":"exchange","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/exchange/src/disruption-response/index.ts"},{"id":"5.5","name":"Self-Service Rebooking","stage":"exchange","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/exchange/src/self-service-rebooking/index.ts"},{"id":"5.6","name":"Waitlist Management","stage":"exchange","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/exchange/src/waitlist-management/index.ts"},{"id":"6.1","name":"Refund Processing","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/refund-processing/index.ts"},{"id":"6.2","name":"ADM Prevention","stage":"settlement","version":"0.2.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/adm-prevention/index.ts"},{"id":"6.3","name":"ADM/ACM Processing","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/adm-acm-processing/index.ts"},{"id":"6.4","name":"Customer Communication","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/customer-communication/index.ts"},{"id":"6.5","name":"Feedback & Complaint","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/feedback-complaint/index.ts"},{"id":"6.6","name":"Loyalty Mileage","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/loyalty-mileage/index.ts"},{"id":"7.1","name":"BSP Reconciliation","stage":"reconciliation","version":"0.2.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/bsp-reconciliation/index.ts"},{"id":"7.2","name":"ARC Reconciliation","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/arc-reconciliation/index.ts"},{"id":"7.3","name":"Commission Management","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/commission-management/index.ts"},{"id":"7.4","name":"Interline Settlement","stage":"reconciliation","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/reconciliation/src/interline-settlement/index.ts"},{"id":"7.5","name":"Financial Reporting","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/financial-reporting/index.ts"},{"id":"7.6","name":"Revenue Accounting","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/revenue-accounting/index.ts"},{"id":"8.1","name":"Traveler Profile","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/traveler-profile/index.ts"},{"id":"8.2","name":"Corporate Account","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/corporate-account/index.ts"},{"id":"8.3","name":"Mid-Office Automation","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/mid-office/index.ts"},{"id":"8.4","name":"Reporting & Analytics","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/reporting/index.ts"},{"id":"8.5","name":"Duty of Care","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/duty-of-care/index.ts"},{"id":"9.1","name":"Orchestrator","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/orchestrator/index.ts"},{"id":"9.2","name":"Knowledge Retrieval","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/knowledge/index.ts"},{"id":"9.3","name":"Monitoring & Alerting","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/monitoring/index.ts"},{"id":"9.4","name":"Audit & Compliance","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/audit/index.ts"},{"id":"9.5","name":"Plugin Manager","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/plugin-manager/index.ts"},{"id":"9.6","name":"Performance Audit","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/performance-audit/index.ts"},{"id":"9.7","name":"Routing Audit","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/routing-audit/index.ts"},{"id":"9.8","name":"Recommendation","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/recommendation/index.ts"},{"id":"9.9","name":"Alert","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/alert/index.ts"},{"id":"20.1","name":"Hotel Search Aggregator","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/hotel-search/index.ts"},{"id":"20.2","name":"Property Deduplication","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/property-dedup/index.ts"},{"id":"20.3","name":"Hotel Content Normalization","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/content-normalization/index.ts"},{"id":"20.4","name":"Hotel Rate Comparison","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/rate-comparison/index.ts"},{"id":"20.5","name":"Hotel Booking","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/hotel-booking/index.ts"},{"id":"20.6","name":"Hotel Modification & Cancellation","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/hotel-modification/index.ts"},{"id":"20.7","name":"Confirmation Verification","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/confirmation-verification/index.ts"},{"id":"20.8","name":"Activity Search","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/activity-search/index.ts"},{"id":"20.9","name":"Transfer Search","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/transfer-search/index.ts"}],"edges":[{"source":"1.1","target":"1.4","kind":"workflow","label":"search_to_price"},{"source":"1.4","target":"2.1","kind":"workflow","label":"search_to_price"},{"source":"2.1","target":"2.2","kind":"workflow","label":"search_to_price"},{"source":"2.2","target":"2.3","kind":"workflow","label":"search_to_price"},{"source":"3.3","target":"3.1","kind":"workflow","label":"book_to_ticket"},{"source":"3.1","target":"3.2","kind":"workflow","label":"book_to_ticket"},{"source":"3.2","target":"4.1","kind":"workflow","label":"book_to_ticket"},{"source":"1.1","target":"1.4","kind":"workflow","label":"full_booking"},{"source":"1.4","target":"2.1","kind":"workflow","label":"full_booking"},{"source":"2.1","target":"2.2","kind":"workflow","label":"full_booking"},{"source":"2.2","target":"2.3","kind":"workflow","label":"full_booking"},{"source":"2.3","target":"3.3","kind":"workflow","label":"full_booking"},{"source":"3.3","target":"3.1","kind":"workflow","label":"full_booking"},{"source":"3.1","target":"3.2","kind":"workflow","label":"full_booking"},{"source":"3.2","target":"4.1","kind":"workflow","label":"full_booking"},{"source":"5.1","target":"5.2","kind":"workflow","label":"exchange_flow"},{"source":"6.1","target":"6.2","kind":"workflow","label":"refund_flow"},{"source":"1.1","target":"0.1","kind":"package","label":"@otaip/agents-search → @otaip/agents-reference"},{"source":"2.1","target":"0.1","kind":"package","label":"@otaip/agents-pricing → @otaip/agents-reference"},{"source":"3.1","target":"0.1","kind":"package","label":"@otaip/agents-booking → @otaip/agents-reference"},{"source":"3.1","target":"1.1","kind":"package","label":"@otaip/agents-booking → @otaip/agents-search"},{"source":"3.1","target":"2.1","kind":"package","label":"@otaip/agents-booking → @otaip/agents-pricing"},{"source":"4.1","target":"3.1","kind":"package","label":"@otaip/agents-ticketing → @otaip/agents-booking"},{"source":"5.1","target":"1.1","kind":"package","label":"@otaip/agents-exchange → @otaip/agents-search"},{"source":"5.1","target":"4.1","kind":"package","label":"@otaip/agents-exchange → @otaip/agents-ticketing"},{"source":"6.1","target":"4.1","kind":"package","label":"@otaip/agents-settlement → @otaip/agents-ticketing"},{"source":"7.1","target":"0.1","kind":"package","label":"@otaip/agents-reconciliation → @otaip/agents-reference"}],"package_deps":[{"from_package":"@otaip/agents-search","to_package":"@otaip/agents-reference","from_stage":"search","to_stage":"reference"},{"from_package":"@otaip/agents-pricing","to_package":"@otaip/agents-reference","from_stage":"pricing","to_stage":"reference"},{"from_package":"@otaip/agents-booking","to_package":"@otaip/agents-reference","from_stage":"booking","to_stage":"reference"},{"from_package":"@otaip/agents-booking","to_package":"@otaip/agents-search","from_stage":"booking","to_stage":"search"},{"from_package":"@otaip/agents-booking","to_package":"@otaip/agents-pricing","from_stage":"booking","to_stage":"pricing"},{"from_package":"@otaip/agents-ticketing","to_package":"@otaip/agents-booking","from_stage":"ticketing","to_stage":"booking"},{"from_package":"@otaip/agents-exchange","to_package":"@otaip/agents-search","from_stage":"exchange","to_stage":"search"},{"from_package":"@otaip/agents-exchange","to_package":"@otaip/agents-ticketing","from_stage":"exchange","to_stage":"ticketing"},{"from_package":"@otaip/agents-settlement","to_package":"@otaip/agents-ticketing","from_stage":"settlement","to_stage":"ticketing"},{"from_package":"@otaip/agents-reconciliation","to_package":"@otaip/agents-reference","from_stage":"reconciliation","to_stage":"reference"}]},"docs":{"0.1":{"id":"0.1","summary":"Resolves IATA/ICAO airport and city codes to canonical airport records with multi-airport city awareness and historical code handling","className":"AirportCodeResolver","input":"`code` -- IATA 3-letter, ICAO 4-letter, city code, or airport name\n`code_type?` -- `'iata' | 'icao' | 'city' | 'name' | 'auto'` (auto-detected if omitted)\n`include_metro?` -- return all airports in a metro/city code (default: true)\n`include_decommissioned?` -- resolve retired/reassigned codes (default: false)","output":"`resolved_airport` -- canonical airport record (IATA, ICAO, name, city, country, timezone, lat/lon, type, status)\n`metro_airports` -- list of airports in the same metro area\n`match_confidence` -- 0-1 confidence score\n`stale_data?` -- true when dataset is older than 30 days\n`suggestion?` -- fuzzy match suggestion when code not found","usage":"const agent = new AirportCodeResolver();\nawait agent.initialize();\nconst result = await agent.execute({ data: { code: 'JFK', code_type: 'iata' } });\n// result.data.resolved_airport.name => \"John F Kennedy International Airport\"","status":"Implemented","purpose":"Resolves IATA/ICAO airport and city codes to canonical airport records with multi-airport city awareness, fuzzy name matching, and historical code handling."},"0.2":{"id":"0.2","summary":"Resolves IATA/ICAO airline designator codes to canonical airline records with alliance membership mapping and codeshare partner networks","className":"AirlineCodeMapper","input":"`code` -- IATA 2-letter, ICAO 3-letter, or airline name\n`code_type?` -- `'iata' | 'icao' | 'name' | 'auto'`\n`include_codeshares?` -- include codeshare partners (default: false)\n`include_defunct?` -- include ceased-operations airlines (default: false)","output":"`airline` -- canonical airline record (codes, name, callsign, country, alliance, hubs, status)\n`codeshare_partners` -- partner airline list with relationship type\n`match_confidence` -- 0-1 confidence score","usage":"const agent = new AirlineCodeMapper();\nawait agent.initialize();\nconst result = await agent.execute({ data: { code: 'UA', include_codeshares: true } });\n// result.data.airline.name => \"United Airlines\"","status":"Implemented"},"0.3":{"id":"0.3","summary":"Decodes ATPCO-standard fare basis codes into human-readable components including cabin class, fare restrictions, advance purchase requirements, and penalty information","className":"FareBasisDecoder","input":"`fare_basis` -- ATPCO fare basis code (max 15 chars, e.g., `\"YOW3M1\"`, `\"TLXP14NR\"`)\n`carrier?` -- IATA airline code for carrier-specific decoding","output":"`decoded` -- parsed components (primary code, cabin class, fare type, season, day-of-week, advance purchase, min/max stay, penalties, ticket designator)\n`match_confidence` -- 1.0 = fully decoded, 0.5-0.9 = partial\n`unparsed_segments` -- parts that could not be decoded","usage":"const agent = new FareBasisDecoder();\nawait agent.initialize();\nconst result = await agent.execute({ data: { fare_basis: 'Y26NR' } });\n// result.data.decoded.cabin_class => \"economy\"","status":"Implemented"},"0.4":{"id":"0.4","summary":"Maps single-letter booking class codes to cabin class, fare family, upgrade eligibility, and loyalty program earning rates","className":"ClassOfServiceMapper","input":"`booking_class` -- single letter A-Z\n`carrier` -- IATA 2-letter airline code (required -- meanings are carrier-specific)\n`include_loyalty?` -- include loyalty earning rates (default: false)","output":"`mapping` -- cabin class, brand name, fare family, upgrade eligibility/type, same-day change, seat selection, refundable, priority level, loyalty earning\n`match_confidence` -- 1.0 = carrier-specific, 0.7 = IATA default, 0 = unknown","usage":"const agent = new ClassOfServiceMapper();\nawait agent.initialize();\nconst result = await agent.execute({ data: { booking_class: 'J', carrier: 'UA', include_loyalty: true } });\n// result.data.mapping.cabin_class => \"business\"","status":"Implemented","purpose":"Maps single-letter booking class codes to cabin class, fare family, upgrade eligibility, and loyalty program earning rates. Booking classes are carrier-specific."},"0.5":{"id":"0.5","summary":"Resolves IATA aircraft equipment codes to structured equipment data","className":"EquipmentTypeResolver","input":"`operation` -- `'resolve' | 'getSeatingConfig' | 'isWidebody' | 'getSimilarTypes'`\n`code` -- IATA equipment code (e.g., `\"789\"`, `\"320\"`)\n`cabin?` -- cabin code (`'F' | 'C' | 'W' | 'Y'`) for `getSeatingConfig`","output":"`equipment?` -- full equipment info (IATA/ICAO codes, manufacturer, family, body type, seats, range)\n`seatCount?` -- seat count for specific cabin\n`isWidebody?` -- boolean\n`similarTypes?` -- IATA codes of similar aircraft","usage":"const agent = new EquipmentTypeResolver();\nawait agent.initialize();\nconst result = await agent.execute({ data: { operation: 'resolve', code: '789' } });\n// result.data.equipment.manufacturer => \"Boeing\"","status":"Implemented","purpose":"Resolves IATA aircraft equipment codes to structured equipment data including manufacturer, body type, typical seating, range, and max capacity."},"0.6":{"id":"0.6","summary":"Resolves ISO 4217 currency codes and IATA tax/surcharge codes used in airline pricing and ticketing","className":"CurrencyTaxResolver","input":"`code` -- ISO currency code or IATA tax code\n`code_type?` -- `'currency' | 'tax' | 'auto'`\n`country?` -- ISO 2-letter country code to filter tax applicability","output":"`currency` -- currency details (code, name, symbol, minor units, countries, active status)\n`tax` -- tax details (code, name, description, category, country, applies-to, percentage flag)\n`match_confidence` -- 0-1 confidence score","usage":"const agent = new CurrencyTaxResolver();\nawait agent.initialize();\nconst result = await agent.execute({ data: { code: 'USD' } });\n// result.data.currency.name => \"US Dollar\"","status":"Implemented"},"0.7":{"id":"0.7","summary":"APIS requirements, visa requirements, restriction levels. Static dataset -- must NOT be used as legal travel advice","className":"CountryRegulatoryResolver","input":"`operation` -- `'getAPISRequirements' | 'getVisaRequirement' | 'getRestrictionLevel'`\n`countryCode?` -- ISO 2-letter (for APIS and restriction)\n`nationalityCode?` -- ISO 2-letter (for visa)\n`destinationCode?` -- ISO 2-letter (for visa)","output":"`apis?` -- APIS requirements (required fields, advance submission hours)\n`visa?` -- visa requirement (type, max stay days)\n`restriction?` -- restriction level 1-4 with summary","usage":"const agent = new CountryRegulatoryResolver();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: { operation: 'getVisaRequirement', nationalityCode: 'US', destinationCode: 'GB' }\n});\n// result.data.visa.requirement => \"visa_free\"","status":"Implemented"},"1.1":{"id":"1.1","summary":"Queries distribution adapters in parallel, normalizes, deduplicates, filters, and sorts flight availability offers","className":"AvailabilitySearch","input":"`origin` -- origin airport/city IATA code\n`destination` -- destination airport/city IATA code\n`departure_date` -- ISO 8601 date\n`return_date?` -- ISO 8601 date for round-trip\n`passengers` -- `PassengerCount[]`\n`cabin_class?` -- `'economy' | 'premium_economy' | 'business' | 'first'`\n`direct_only?` -- only direct flights\n`max_connections?` -- 0-5\n`currency?` -- ISO 4217\n`max_results?` -- 1-200\n`sort_by?` -- `'price' | 'duration' | 'departure' | 'arrival' | 'connections'`\n`sort_order?` -- `'asc' | 'desc'`\n`sources?` -- specific adapter names to query","output":"`offers` -- deduplicated, filtered, sorted `SearchOffer[]`\n`total_raw_offers` -- count before deduplication\n`source_status` -- per-adapter query status (success, count, error, response time)\n`truncated` -- whether results were capped","usage":"new AvailabilitySearch(adapters: DistributionAdapter[]) Then call initialize() and execute({ data }).","status":"Implemented"},"1.2":{"id":"1.2","summary":"Looks up flight schedules with SSIM operating day parsing, codeshare detection, and connection discovery","className":"ScheduleLookup","input":"`origin` -- airport IATA code\n`destination` -- airport IATA code\n`date` -- ISO 8601 date\n`carrier?` -- filter by carrier IATA code\n`flight_number?` -- specific flight (requires carrier)\n`include_codeshares?` -- default: true\n`include_connections?` -- discover connecting options (default: false)","output":"`flights` -- `ScheduledFlight[]` (carrier, flight number, times, duration, schedule, codeshare info)\n`connections` -- `ConnectionOption[]` (two-leg connections with timing)\n`operates_on_date` -- whether any flights operate on the requested date","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.3":{"id":"1.3","summary":"Validates connections against MCT rules, scores connection quality, and checks interline agreements","className":"ConnectionBuilder","input":"`arriving_segment` -- `FlightSegment` (from `@otaip/core`)\n`departing_segment` -- `FlightSegment`\n`connection_airport` -- IATA 3-letter code\n`has_checked_bags?` -- affects MCT\n`is_interline?` -- different carriers","output":"`validation` -- MCT check result (valid, available/required minutes or null when unavailable, buffer, applied rule)\n`quality` -- connection quality score 0-1 with factor breakdown\n`interline` -- interline agreement check (if different carriers)\n`warnings` -- connection warnings","status":"Implemented","purpose":"Validates connections against MCT (Minimum Connecting Time) rules, scores connection quality, and checks interline agreements.\n\nMCT authority: **IATA SSIM Chapter 8** + **PSC Resolution 765** (`docs/knowledge-base/mct.md`). Curated rows live under `data/reference/mct/`. Resolution hierarchy: carrier override → airport+terminal → airport → **fail-closed** (no invented global/airport-constant table).","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.4":{"id":"1.4","summary":"Multi-source fare comparison with fare basis decoding, class mapping, branded fare family grouping, and passenger type pricing","className":"FareShopping","input":"`origin`, `destination`, `departure_date`, `passengers` -- same as availability search\n`cabin_class?`, `currency?`, `sources?` -- filters\n`decode_fare_basis?` -- decode fare basis codes (default: true)\n`group_by_fare_family?` -- group by basic/standard/flex/premium (default: true)","output":"`fares` -- `FareOffer[]` sorted by price, each with decoded fare basis, class info, fare family, passenger pricing\n`fare_families` -- grouped by family with cheapest/most expensive\n`total_fares` -- count\n`sources_queried` -- adapter names","usage":"new FareShopping(adapters: DistributionAdapter[]) Then call initialize() and execute({ data }).","status":"Implemented"},"1.5":{"id":"1.5","summary":"Searches ancillary offers (seats, bags, meals) across distribution adapters","className":"AncillaryShoppingAgent","input":"`segments` -- flight segments (origin, destination, flight number, date, carrier)\n`passengers` -- passenger references with type (ADT/CHD/INF)\n`pnrRef?` -- PNR reference\n`requestedCategories?` -- filter by category (BAGGAGE, SEAT, MEAL, etc.)","output":"`ancillaries` -- `AncillaryOffer[]` with RFIC/RFISC codes, pricing, availability\n`notSupportedByAdapter` -- true if no adapter configured\n`currency` -- pricing currency","status":"Implemented","purpose":"Searches for available ancillaries (baggage, seats, meals, lounge, Wi-Fi, priority) via an injectable adapter.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.6":{"id":"1.6","summary":"Deduplicates and normalizes flight results from multiple adapter sources","className":"MultiSourceAggregatorAgent","input":"`results` -- `AdapterSearchResult[]` (adapter name, flights, errors, response time)\n`deduplicationStrategy` -- `'keep_cheapest' | 'keep_all' | 'keep_first'`\n`rankBy` -- `'price' | 'duration' | 'stops'`\n`maxResults?` -- limit output count","output":"`flights` -- `NormalizedFlight[]` with sources, lowest price, all prices across adapters\n`totalRaw` -- raw count before dedup\n`totalAfterDedup` -- final count\n`adapterSummary` -- per-adapter stats","status":"Implemented","purpose":"Aggregates search results from multiple adapters with deduplication, price comparison, and ranking.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.7":{"id":"1.7","summary":"Stub agent for hotel and car rental search via distribution adapters","className":"HotelCarSearchAgent","input":"`operation` -- `'searchHotels' | 'searchCars'`\n`hotel?` -- hotel search params (destination, dates, rooms, adults, star rating, max rate)\n`car?` -- car search params (pickup/dropoff location and times, category, driver age)","output":"`hotelResults?` -- hotel offers with rate, room type, cancellation policy\n`carResults?` -- car offers with category, supplier, daily/total rate, features","status":"Implemented (adapter-dependent)","purpose":"Car rental search (and, pending a deferred car-only migration, hotel) via pluggable adapters. Returns empty results when no adapters configured.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.8":{"id":"1.8","summary":"Natural language travel query understanding with injectable LLM provider; parses user queries into structured search parameters","className":"AITravelAdvisorAgent","input":"`query` -- natural language travel query\n`travelerContext?` -- preferences (cabin, budget, preferred airlines, passenger counts)","output":"`searchParameters` -- extracted origin, destination, dates, trip type, cabin, passengers, flexible dates\n`summary` -- natural language summary of interpreted query\n`intent` -- `'flight_search' | 'hotel_search' | 'destination_recommendation' | 'price_check' | 'trip_planning' | 'unknown'`","usage":"new AITravelAdvisorAgent({ llmProvider, maxTokens?, temperature? }) Then call initialize() and execute({ data }).","status":"Implemented"},"1.9":{"id":"1.9","summary":"Stateless, deterministic scoring engine for flight offers with multi-dimensional scoring, hard filtering, and full audit trail (lives in @otaip/core)","className":"OfferEvaluatorAgent","input":"`offers` -- `EvaluatorOffer[]` with price, itinerary (segments, duration, connections)\n`constraints?` -- latest arrival, prefer direct, max connections, price ceiling, preferred/blacklisted carriers\n`profile?` -- `'BUSINESS_TIME_CRITICAL' | 'BUSINESS_PRICE_CONSTRAINED' | 'LEISURE' | 'CORPORATE_POLICY' | 'CUSTOM'`\n`weights?` -- custom scoring weights (time_buffer, price, connection_quality, journey_duration)","output":"Scored and ranked offers with structured explanation for LLM translation","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.1":{"id":"2.1","summary":"Parses ATPCO fare rules (categories 1-20) into human-readable structured format using curated tariff snapshot data","className":"FareRuleAgent","input":"`fare_basis` -- fare basis code\n`carrier` -- marketing carrier IATA code\n`origin` -- origin IATA code\n`destination` -- destination IATA code\n`travel_date?` -- ISO date for date-based rule filtering\n`categories?` -- specific ATPCO categories 1-50 (all if omitted)","output":"`rules` -- `FareRuleResult[]` with parsed categories, penalty summary, advance purchase, min/max stay, seasonality\n`total_rules` -- count of matched rules\n`valid_for_date` -- whether fare is valid for the specified travel date\n`in_blackout` -- whether travel date falls in a blackout period","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.2":{"id":"2.2","summary":"NUC x ROE fare construction with mileage validation, HIP/BHC/CTM checks, surcharges, and IATA rounding. All financial math uses decimal.js","className":"FareConstruction","input":"`journey_type` -- `'OW' | 'RT' | 'CT'` (one-way, round-trip, circle-trip)\n`components` -- fare components (origin, destination, carrier, fare basis, NUC amount)\n`selling_currency` -- ISO 4217 currency\n`point_of_sale?` -- country for IROE selection context\n`data_sources?` -- licensed `{ iroe, rounding_024d, mileage }` (required for a constructed fare)","output":"Success (`FareConstructionOutput`): `total_nuc`, `iroe` (alias `roe`), `local_amount` after 024d, `rounding_method` (`HX`|`NX`), published `mileage_checks`, HIP/BHC/CTM sketches, `audit_trail`\nOr `DomainInputRequired` when licensed data is missing","status":"Implemented","purpose":"NUC × IROE construction with published TPM/MPM, Resolution **024d** (HX/NX) rounding, and fail-closed HIP/BHC/CTM hooks. All financial math uses `decimal.js`.\n\nLicensed IROE / 024d / TPM-MPM data are **not** shipped in the package. Pass them via `data_sources`. Missing IROE, TPM, or 024d → `DomainInputRequired`. Haversine-as-TPM and banker's rounding are banned.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.3":{"id":"2.3","summary":"Per-segment tax computation with exemption engine, ~30 countries, ~50 tax codes, currency conversion. All financial math uses decimal.js","className":"TaxCalculation","input":"`segments` -- itinerary segments (origin/destination airports and countries, carrier, cabin class, base fare NUC)\n`passenger_type` -- `'adult' | 'child' | 'infant' | 'crew' | 'diplomatic'`\n`is_transit` -- whether transit/connection (\u003c 24h same ticket)\n`is_involuntary` -- whether involuntary reroute\n`total_base_fare_nuc` -- total base fare for percentage-based taxes\n`selling_currency` -- ISO 4217","output":"`taxes` -- `AppliedTax[]` (code, name, country, type, amounts, segment indices, interlineable, exempt status)\n`total_tax` -- total in selling currency\n`breakdown` -- by country, interlineable/non-interlineable totals\n`exemptions_applied` -- list of exemption reasons\n`segments_processed` -- count","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.4":{"id":"2.4","summary":"Builds priced offers with TTL management and optional persistence adapter","className":"OfferBuilderAgent","input":"`operation` -- `'buildOffer' | 'getOffer' | 'validateOffer' | 'markUsed' | 'expireOffer' | 'cleanExpired'`\n`buildInput?` -- segments, fare, taxes, ancillaries, passenger count, pricing source, TTL\n`offerId?` -- for get/validate/mark/expire operations\n`currentTime?` -- ISO timestamp override","output":"`offer?` -- full offer record with pricing breakdown, TTL, status\n`valid?` -- offer validity result\n`reason?` -- validation failure reason\n`cleanedCount?` -- number of expired offers cleaned","usage":"new OfferBuilderAgent({ persistence?: PersistenceAdapter }) Then call initialize() and execute({ data }).","status":"Implemented","purpose":"Builds, caches, validates, and manages pricing offers with TTL expiration. Supports in-memory or pluggable persistence."},"2.5":{"id":"2.5","summary":"Validates flight offers against corporate travel policies (cabin, budget, advance purchase)","className":"CorporatePolicyValidationAgent","input":"`offer` -- offer details (cabin, fare amount, carrier, fare basis, advance booking days, segments)\n`policy` -- corporate policy (cabin rules, fare rules, booking rules, bypass codes)\n`bypassCode?` -- authorization code to bypass soft violations","output":"`result` -- `'APPROVED' | 'SOFT_VIOLATION' | 'HARD_VIOLATION'`\n`violations` -- `PolicyViolation[]` with rule, severity, detail\n`bypassApplied` -- whether bypass was used","status":"Implemented","purpose":"Validates flight offers against corporate travel policies: cabin class limits, fare ceilings, blocked carriers, advance booking requirements. Supports bypass codes.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.6":{"id":"2.6","summary":"Placeholder -- not yet implemented. Requires revenue management integration","className":"DynamicPricingAgent","status":"Coming Soon (stub)","purpose":"Revenue management integration for dynamic fare adjustments. Requires revenue management integration before implementation can proceed.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"2.7":{"id":"2.7","summary":"Placeholder -- not yet implemented. Requires revenue management integration","className":"RevenueManagementAgent","status":"Coming Soon (stub)","purpose":"Revenue management system integration. Requires revenue management domain input before implementation can proceed.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"3.1":{"id":"3.1","summary":"Routes booking requests to the correct distribution channel based on carrier config, codeshare rules, and NDC capability","className":"GdsNdcRouter","input":"`segments` -- routing segments (marketing/operating carrier, origin, destination, flight number)\n`transaction_type` -- `'shopping' | 'booking' | 'ticketing' | 'servicing' | 'group' | 'corporate'` (aliases for matrix labels Shop / OrderCreate / Servicing|OrderChange|OrderCancel / Groups / Corporate)\n`vendor?` -- `'sabre' | 'amadeus' | 'duffel' | 'navitaire' | 'trippro' | 'airline_direct' | 'unknown'` (required for unambiguous matrix lookup)\n`plating_carrier?` -- when plating ≠ marketing/operating (DOMAIN_QUESTION on precedence)\n`capability_matrix?` -- inline KB CSV-shaped rows; preferred over airline→channel maps\n`capability_overrides?` -- per-carrier, per-transaction escape hatch when matrix cell is unknown\n`preferred_channel?` -- `'GDS' | 'NDC' | 'DIRECT'`\n`preferred_gds?` -- `'AMADEUS' | 'SABRE' | 'TRAVELPORT'`\n`include_fallbacks` -- whether to include fallback channels","output":"`routings` -- per-segment channel routing (primary channel, GDS system, NDC version, fallbacks, booking format); `domain_input_required` when matrix/override missing\n`unified_channel` -- whether all segments can use the same channel\n`recommended_channel` -- best channel for entire itinerary\n`gds_format` / `ndc_format` -- format translation stubs (`ndc_format` omitted when version unknown — never invents `21.3`)","status":"Implemented","purpose":"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`).","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.2":{"id":"3.2","summary":"Constructs GDS-ready PNR commands from normalized booking data. Supports Amadeus, Sabre, and Travelport syntax","className":"PnrBuilder","input":"`gds` -- `'AMADEUS' | 'SABRE' | 'TRAVELPORT'`\n`passengers` -- name, type, DOB, passport, gender, nationality, FOID\n`segments` -- carrier, flight, class, date, origin, destination, status\n`contacts` -- phone, email, type\n`ticketing` -- time limit, type\n`received_from` -- agent identifier\n`ssrs?` -- SSR elements (WCHR, VGML, DOCS, FOID, CTCE, CTCM, INFT)\n`osis?` -- OSI elements\n`is_group?` / `group_name?` -- group PNR support","output":"`gds` -- target GDS\n`commands` -- ordered `PnrCommand[]` with GDS command strings and descriptions\n`passenger_count`, `segment_count`, `is_group`, `infant_count`","status":"Implemented","purpose":"Constructs GDS-ready PNR commands from normalized booking data. Supports Amadeus, Sabre, and Travelport syntax including names, segments, contacts, ticketing, SSR/OSI elements, and group bookings.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.3":{"id":"3.3","summary":"Pre-ticketing validation -- 13 checks to catch errors before ADMs","className":"PnrValidation","input":"`record_locator` -- 6-char PNR\n`passengers` -- passenger data (name, type, DOB, nationality, passport)\n`segments` -- segment data (carrier, flight, status, class, international flag, married group)\n`contact?` -- phone/email\n`ticketing?` -- time limit, arranged status\n`fare?` -- fare data with advance purchase deadline\n`validation_date?` -- ISO date override","output":"`record_locator` -- PNR\n`checks` -- `ValidationCheck[]` (13 checks, each with pass/fail, severity, message)\n`valid` -- overall pass/fail\n`error_count`, `warning_count`","status":"Implemented","purpose":"Pre-ticketing validation with 13 checks to catch errors before ADMs: segment status, passenger data, APIS, ticketing deadline, fare consistency, and more.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.4":{"id":"3.4","summary":"GDS queue monitoring and processing -- priority assignment, categorization, action routing, and queue command generation","className":"QueueManagement","input":"`entries` -- queue items (record locator, GDS, queue number, entry type, deadline, remark)\n`current_time?` -- ISO timestamp for priority calculation\n`gds?` -- GDS system for command generation\n`queue_number?` -- queue to generate read commands for\n`travelport_host?` -- `'APOLLO' | 'GALILEO' | 'WORLDSPAN'` when `gds` is `TRAVELPORT`","output":"`results` -- processed items with priority, status, recommended action, target agent\n`commands?` -- GDS queue commands\n`summary` -- counts by priority (urgent/high/normal/low)","status":"Implemented","purpose":"GDS queue monitoring and processing: priority assignment, categorization, action routing, and queue command generation.\n\nTravelport place/list/remove commands are **per host** (Apollo / Galileo≡Travelport+ / Worldspan) from the public format-compare table — see `docs/knowledge-base/tmc-mid-office-ttl-queues.md`. TTL priority uses Zulu deadline-day urgency.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.5":{"id":"3.5","summary":"Universal HTTP client with circuit breaker, retry logic, timeout handling, rate limiting, and IATA error normalization","className":"ApiAbstraction","input":"`request` -- API request (provider ID, HTTP method, path, headers, body)\n`max_retries?` -- override retry count\n`timeout_ms?` -- override timeout\n`force?` -- skip circuit breaker check","output":"`response` -- API response (status, headers, body, duration, retries)\n`error` -- normalized error (category, original code, retryable flag)\n`circuit_breaker` -- circuit breaker status\n`rate_limit` -- rate limit status\n`success` -- boolean","usage":"new ApiAbstraction(handler?: RequestHandler) Then call initialize() and execute({ data }).","status":"Implemented","purpose":"Universal HTTP client with circuit breaker, retry logic, timeout handling, rate limiting, and IATA error normalization for GDS/NDC/payment providers."},"3.6":{"id":"3.6","summary":"Travel order lifecycle management -- create, modify, cancel, retrieve, and list orders with status tracking and transition validation","className":"OrderManagement","input":"`operation` -- `'createOrder' | 'modifyOrder' | 'cancelOrder' | 'getOrder' | 'listOrders'`\n`createOrder?` -- passenger, items, currency, source\n`modifyOrder?` -- order ID, updated items/details, reason\n`cancelOrder?` -- order ID, reason\n`getOrder?` / `listOrders?` -- retrieval/filtering","output":"`order?` -- order record with status, items, history\n`orders?` -- list of orders\n`operation`, `success`, `errorCode?`, `errorMessage?`","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.7":{"id":"3.7","summary":"PCI-safe payment instruction builder and transaction recorder. Validates forms of payment, builds GDS FOP strings -- never handles raw card numbers","className":"PaymentProcessing","input":"`operation` -- `'validateFOP' | 'buildPaymentInstruction' | 'recordPayment' | 'getPaymentRecord' | 'buildGDSFOPString'`\nOperation-specific data: FOP details (CC_TOKEN, BSP_CASH, AIRLINE_CREDIT, VOUCHER, UATP), amounts, references","output":"`validation?` -- FOP validation result\n`instruction?` -- payment instruction with GDS string, PCI-safe flag\n`record?` -- payment transaction record\n`gdsString?` -- GDS FOP string","status":"Implemented","purpose":"PCI-safe payment instruction builder and transaction recorder. Validates forms of payment, builds GDS FOP strings, records transactions. Never handles raw card numbers.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.8":{"id":"3.8","summary":"Retrieves an existing PNR/booking by record locator across distribution adapters. Read-only -- no side effects","className":"PnrRetrieval","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"4.1":{"id":"4.1","summary":"ETR generation with conjunction ticket support, BSP reporting, and commission handling","className":"TicketIssuance","input":"`record_locator` -- 6-char PNR\n`issuing_carrier` -- 2-letter IATA code\n`passenger_name` -- LAST/FIRST format\n`segments` -- flight segments with carrier, flight number, class, fare basis, dates, baggage\n`base_fare`, `base_fare_currency` -- fare amount\n`equivalent_fare?`, `equivalent_fare_currency?` -- currency conversion\n`taxes` -- tax breakdown items\n`fare_calculation` -- fare calculation line\n`form_of_payment` -- CASH, CREDIT_CARD, INVOICE, MISCELLANEOUS\n`endorsements?`, `commission?`, `bsp_reporting?`, `original_issue?`","output":"`tickets` -- `TicketRecord[]` (13-digit number, coupons with status, fare/tax breakdown, FOP, commission, BSP fields)\n`total_coupons` -- total across all tickets\n`is_conjunction` -- whether conjunction tickets were generated","status":"Implemented","purpose":"ETR (Electronic Ticket Record) generation with conjunction ticket support (auto-split for >4 coupons), BSP reporting fields, and commission handling.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"4.2":{"id":"4.2","summary":"EMD-A (associated) and EMD-S (standalone) issuance, RFIC/RFISC handling, coupon lifecycle","className":"EmdManagement","input":"`emd_type` -- `'EMD-A' | 'EMD-S'`\n`record_locator`, `issuing_carrier`, `passenger_name`\n`services` -- array of services with RFIC code (A-G), RFISC, description, amount, associated ticket/coupon for EMD-A\n`related_ticket_number?` -- for EMD-A","output":"`emd` -- `EmdRecord` (13-digit EMD number, coupons, amounts)\n`coupon_count`","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"4.3":{"id":"4.3","summary":"Ticket/EMD void processing -- coupon status check, carrier void window, BSP/ARC cut-off validation","className":"VoidAgent","input":"`document_number` -- 13-digit ticket/EMD number\n`issuing_carrier` -- 2-letter IATA code\n`coupons` -- coupon numbers and current statuses\n`issue_datetime` -- ISO datetime of issuance\n`current_datetime?` -- ISO datetime for void window check\n`settlement_system?` -- `'BSP' | 'ARC'`\n`bsp_cutoff_time?` -- HH:MM format","output":"`result` -- void permitted flag, rejection reason, message, void window hours, hours remaining, updated coupon statuses","status":"Implemented","purpose":"Ticket/EMD void processing with coupon status validation, carrier-specific void window enforcement, and BSP/ARC cut-off time checking.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"4.4":{"id":"4.4","summary":"Multi-channel itinerary rendering: Email (HTML+plain), SMS, WhatsApp. Carrier-neutral templates","className":"ItineraryDelivery","input":"`record_locator` -- booking reference\n`passengers` -- name, ticket number, frequent flyer\n`flights` -- flight details (number, origin, destination, times, cabin, seat, aircraft)\n`total_fare?`, `fare_currency?`\n`contact` -- email, phone, WhatsApp number\n`channels` -- `('EMAIL' | 'SMS' | 'WHATSAPP')[]`\n`agency_name?` -- for itinerary header","output":"`rendered` -- per-channel content (HTML/plain text, subject, SMS segment count)\n`channels_rendered` -- successfully rendered channels","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"4.5":{"id":"4.5","summary":"APIS validation, passport validity, visa check (stub for Agent 0.7)","className":"DocumentVerification","input":"`passengers` -- ticket name, passport name, passport number/expiry/nationality, DOB, gender\n`segments` -- destination country and travel date\n`passport_validity_months?` -- minimum validity beyond travel date (default: 6)\n`validation_date?` -- ISO date override","output":"`results` -- per-passenger verification (pass/fail, individual checks with severity)\n`all_passed` -- overall pass/fail\n`blocking_failures`, `advisory_warnings` -- counts","status":"Implemented","purpose":"APIS validation, passport validity checking (configurable months threshold), and name matching between ticket and passport.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"5.1":{"id":"5.1","summary":"ATPCO Category 31 voluntary change assessment: change fees, fare difference, residual value, waiver codes","className":"ChangeManagement","input":"`original_ticket` -- ticket number, issuing carrier, passenger name, record locator, issue date, base fare, total tax, fare basis, refundable flag, booking date, `original_departure_date?` (for DOT 7-day check)\n`requested_itinerary` -- new segments (carrier, flight, origin, destination, date, class, fare basis), new fare, new taxes\n`waiver_code?` -- airline-provided waiver identity (not skip-penalty by itself)\n`waiver_effect?` -- required when `waiver_code` set: `ELIMINATE_PENALTY | REDUCE_PENALTY | CHANGE_REFUND_FORM | CHANGE_REBOOKING_CLASS | IRROP_INVOLUNTARY` (see `docs/knowledge-base/waiver-typology.md`)\n`waiver_penalty_reduction?` -- required for `REDUCE_PENALTY`\n`permitted_booking_classes?` / `permitted_fare_basis_patterns?` -- required for `CHANGE_REBOOKING_CLASS`\n`current_datetime?` -- ISO datetime\n`cat31_rules?` -- filed Cat 31 rules (omit → ATPCO default no charge)\n`us_dot_24h?` -- `part_259_applicable?`, `booking_channel?` (`airline_direct` | `agency` | `ndc` | `gds` | `unknown`)","output":"`assessment` -- action (`REISSUE | REBOOK | REJECT`), change fee, fare difference, additional collection, residual value, forfeited amount, tax difference, total due, Cat 31 `is_free_change` flag, summary\n`us_dot_24h` -- carrier remedy (`cancel` | `hold` | `unknown`), eligibility, ineligibility reasons (including `departure_within_7_days`, `channel_coverage_unknown`), entitlement (`penalty_free_cancel` | `unpaid_fare_hold` | `none` | `unknown`). **Not** a free-change boolean. Channel coverage follows carrier disclosure — not a baked-in “third-party never qualifies” rule.","status":"Implemented","purpose":"ATPCO Category 31 voluntary change assessment: change fees, fare difference, residual value, waiver codes, Cat 31 free-change window detection, and US DOT 14 CFR §259.5(b)(4) 24-hour reservation assessment (hold **or** cancel — carrier chooses; ≥7 days before departure). See `docs/knowledge-base/us-dot-24-hour-reservation.md`.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"5.2":{"id":"5.2","summary":"Ticket reissue with residual value, per-tax TFC carryforward (CARRY\\","className":"ExchangeReissue","input":"`original_ticket_number`, `conjunction_originals?`, `original_issue_date`\n`issuing_carrier`, `passenger_name`, `record_locator`\n`original_base_fare`, `original_taxes` -- from original ticket\n`change_fee`, `residual_value`, `waiver_code?` -- from Agent 5.1\n`new_segments` -- new flight segments\n`new_fare`, `new_fare_currency`, `new_taxes`, `fare_calculation`\n`form_of_payment` -- for additional collection\n`gds?` -- GDS for command generation\n`tax_carryforward_context` -- geography (`SAME_AIRPORT | SAME_CITY | DIFFERENT`), validity window flag, flown status, POS unchanged\n`tax_carryforward_rules` -- per-code rules covering every tax on original ∪ new (nature, min geography, YQ/YR flags, validity expiry action)\n`same_origin_destination?` -- **deprecated / ignored** for tax decisions (migration warning only)","output":"`reissue` -- new ticket record with full audit trail, exchange commands, `tax_decisions` on the audit trail\n`additional_collection` -- amount due\n`credit_amount` -- amount refundable if downgrade\n`tax_decisions` -- `{ tax_code, action: CARRY | RECALCULATE | FORFEIT, reason }[]`","status":"Implemented","purpose":"Ticket reissue with residual value application, **per-tax** carryforward (`CARRY | RECALCULATE | FORFEIT`), conjunction ticket handling, GDS exchange command generation, and full audit trail.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"5.3":{"id":"5.3","summary":"Carrier-initiated schedule change handling: trigger assessment, airline protection logic, regulatory entitlements (EU261, US DOT)","className":"InvoluntaryRebook","input":"`original_pnr` -- record locator, passenger, affected segment, issuing carrier, countries, checked-in flag, EU/Community carrier flag, optional endorsement\n`schedule_change` -- change type (incl. MISCONNECT), times, routing/equipment, misconnect shortfall\n`available_flights?` -- protection candidates with operating/marketing/alliance/interline + `endorsement_allows`\n`thresholds?` -- carrier-specific `time_change_minutes`, `measurement_point` (DEPARTURE|ARRIVAL), `misconnect_minutes` — required for those triggers\n`is_passenger_no_show?` -- no-show flag\n`is_oversale_denied_boarding?` -- only true for 14 CFR §250 oversales\n`eu261_inputs?` -- great-circle `distance_km` (Art.7(4)), delay/notice/rerouting/extraordinary, third-country benefits caveat","output":"`result` -- involuntary flag, trigger, ranked protection candidates (not executed), `art8_passenger_choice_required` + `art8_choices`, measurement point, regulatory flags (EU261/US DOT), original routing credit flag, summary","status":"Implemented","purpose":"Carrier-initiated schedule change / IRROP handling. Domain KB: `docs/knowledge-base/involuntary-rebook-irrop.md` (Regulation (EC) No 261/2004 — [CELEX:32004R0261](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32004R0261)).\n\n- **Triggers:** time change, routing change, equipment downgrade, cancellation, misconnect — with explicit dep vs arr measurement. **No hardcoded 60-minute threshold**; fail closed when carrier threshold input is missing.\n- **Reprotection candidates:** same operating → marketing → alliance → interline → other, with endorsement fail-closed. Alliance ≠ any alliance flight. **Do not silently \"same carrier first\"** — when EU261 applies, Art.8 passenger choice (refund vs re-route) is required before execution.\n- **EU261:** Art.3(1) matrix (EU depart any carrier / EU arrive Community carrier only). Art.7 compensation via great-circle bands only (never TPM). Art.8 choice surfaced on output.\n- **US DOT:** 14 CFR §250 IDB is oversale-specific — delays/cancels report `applies: false`.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"5.4":{"id":"5.4","summary":"Placeholder -- not yet implemented. Requires domain input on disruption priority rules","className":"DisruptionResponseAgent","status":"Coming Soon (stub)","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"5.5":{"id":"5.5","summary":"Placeholder -- not yet implemented. Requires domain input on change fee structures","className":"SelfServiceRebookingAgent","status":"Implemented","purpose":"Orchestrates Availability Search (1.1) and Change Management (5.1) to present priced rebooking alternatives (changeFee + fareDifference + taxDifference per option). Read-only -- does NOT execute the reissue; that is Exchange/Reissue (5.2). Involuntary reasons (schedule change / missed connection / cancellation) waive the change fee; voluntary changes honor ATPCO Cat 31 via 5.1.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"5.6":{"id":"5.6","summary":"Placeholder -- not yet implemented. Requires domain input on waitlist priority scoring","className":"WaitlistManagementAgent","status":"Implemented","purpose":"Stateful in-memory passenger waitlist queue with four operations: addEntry (priority computed at add time), clear (given N seats opened, remove top-N by priority), queryStatus (1-based position + estimated clearance probability), and expire (prune entries past their cutoff). State is in-memory only -- production deployments should pair it with a durable persistence layer.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"6.1":{"id":"6.1","summary":"ATPCO Category 33 refund processing: penalty application, commission recall, BSP/ARC reporting, conjunction ticket handling","className":"RefundProcessing","input":"`ticket_number`, `conjunction_tickets?`\n`issuing_carrier`, `passenger_name`, `record_locator`\n`base_fare`, `base_fare_currency`, `taxes`, `commission?`\n`refund_type` -- `'FULL' | 'PARTIAL' | 'TAX_ONLY'`\n`coupons_to_refund?` -- specific coupons (for partial)\n`total_coupons`, `waiver_code?`, `waiver_effect?` (required with code), `fare_basis`, `is_refundable`\n`waiver_penalty_reduction?`, `waiver_refund_form?` -- companions per typology in `docs/knowledge-base/waiver-typology.md`\n`settlement_system` -- `'BSP' | 'ARC'`","output":"`refund` -- penalty applied, base fare refund, tax refund, tax breakdown, commission recalled, net refund, BSP/ARC reporting fields, audit trail\n`net_refund_amount`, `commission_recalled`","status":"Implemented","purpose":"ATPCO Category 33 refund processing: penalty application, commission recall, BSP/ARC reporting fields, conjunction ticket handling. Supports full, partial, and tax-only refunds.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.2":{"id":"6.2","summary":"Pre-ticketing audit: 10 checks covering fare integrity, passive/UC/churn (history-required), married integrity, TTL, and compliance to prevent Agency Debit Memos","className":"ADMPrevention","input":"`booking` -- record locator, passenger name, segments (with status, class, married group), base fare\n`fare_basis`, `booked_class`\n`commission_rate?`, `carrier_contracted_rate?` -- both caller-supplied; no embedded carrier tables\n`endorsement?`, `tour_code?`\n`is_net_remit?`, `net_contracted_amount?`\n`ttl_deadline?`, `ttl_timezone?`, `ttl_source?`, `current_datetime?`\n`duplicate_check_pnrs?`\n`segment_history?` -- required for churning; current status alone is insufficient\n`gds?` -- `SABRE` | `AMADEUS` | `TRAVELPORT` | `UNKNOWN` (Travelport DX marriage break)\n`churn_cycle_threshold?`, `churn_window_hours?`","output":"`result` -- all check results, overall pass/fail, blocking/warning counts","status":"Implemented","purpose":"Pre-ticketing audit with 10 checks: duplicate booking, fare/class mismatch, passive/unable/risky status (core HX/UC/UN/NO/TK + **per-host** maps — HN/PK/GK/YK are not universalized), churning (history-required), married segment integrity, TTL expiry (timezone / deadline-day), commission rate (caller-supplied only), endorsement box, tour code format, net remit validation.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.3":{"id":"6.3","summary":"Agency Debit Memo receipt, assessment, dispute, and Agency Credit Memo application workflows","className":"ADMACMProcessingAgent","input":"`operation` -- `'receiveADM' | 'receiveACM' | 'assessADM' | 'disputeADM' | 'acceptADM' | 'escalateADM' | 'applyACM' | 'getADM' | 'getPendingWithDeadlines'`\nOperation-specific fields: ticket number, airline, amount, reason code, dispute ground/evidence, ADM/ACM IDs","output":"`adm?` -- ADM record with status history\n`acm?` -- ACM record\n`assessment?` -- days remaining, window expired, recommended action\n`disputeResult?` -- dispute outcome\n`pendingDeadlines?` -- urgent ADMs approaching deadline","status":"Implemented","purpose":"Agency Debit Memo receipt, assessment, dispute, and Agency Credit Memo application workflows. Tracks dispute deadlines (15-day window), supports dispute grounds, and manages status transitions.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.4":{"id":"6.4","summary":"Multi-channel customer notification generation for flight disruptions, refunds, and operational changes. 8 notification types x 4 channels","className":"CustomerCommunication","input":"`operation` -- `'generateNotification' | 'generateBatch' | 'getTemplate'`\n`notificationType?` -- notification type\n`channel?` -- delivery channel\n`variables?` -- template variables (passenger name, flight info, amounts, etc.)\n`batchRequests?` -- for batch generation","output":"`notification?` -- generated notification with body, subject, SMS segments, used/missing variables\n`notifications?` -- batch results\n`template?` -- template info with required variables","status":"Implemented","purpose":"Multi-channel customer notification generation. 8 notification types (flight cancelled, delayed, gate change, rebooking confirmed, refund processed, schedule change, waitlist cleared, ADM received) x 4 channels (Email HTML, Email text, SMS, WhatsApp).","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.5":{"id":"6.5","summary":"Complaint submission, EU261/US DOT compensation calculation, case management, and regulatory DOT record generation","className":"FeedbackComplaintAgent","input":"`operation` -- `'submitComplaint' | 'updateStatus' | 'getCase' | 'listCases' | 'calculateCompensation' | 'generateDOTRecord'`\nComplaint fields: type, passenger, booking reference, airline, flight, description\nCompensation fields: regulation, distance, delay, alternative offered, fare paid, cabin class\nCase management: case ID, status transitions","output":"`complaintCase?` -- full case record with status history, compensation result\n`cases?` -- filtered case list\n`compensation?` -- EU261/US DOT calculation (eligibility, base/final amount, reduction, notes)\n`dotRecord?` -- DOT regulatory record","status":"Implemented","purpose":"Complaint submission, EU261/US DOT compensation calculation, case management with status tracking, and DOT regulatory record generation.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.6":{"id":"6.6","summary":"Mileage accrual calculation, redemption eligibility, status benefits, and alliance status matching","className":"LoyaltyMileageAgent","input":"`operation` -- `'calculateAccrual' | 'checkRedemptionEligibility' | 'getStatusBenefits' | 'matchStatus'`\nAccrual: operating/crediting carrier, booking class, distance, loyalty status\nRedemption: distance, cabin, partner flag, current balance\nBenefits: airline, status tier\nMatch: source/target airline, source status","output":"`accrual?` -- base miles, bonus miles, total, earn rate, partner flag\n`redemption?` -- eligibility, miles required, remaining balance\n`statusBenefits?` -- benefit list by tier\n`statusMatch?` -- matched status at target airline","status":"Implemented","purpose":"Mileage accrual calculation, redemption eligibility checking, status benefits lookup, and cross-airline status matching.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.1":{"id":"7.1","summary":"Matches agency booking records against BSP HOT files, validates commission, identifies discrepancies, flags issues before remittance deadline","className":"BSPReconciliation","input":"`hot_records` -- BSP HOT file records (ticket number, passenger, origin/destination, airline, amounts, commission, transaction type / DISH TRNC, **transaction currency CUTP**, optional reporting currency, billing period, ORIT / RTDN / conjunction set)\n`agency_records` -- agency-side booking records for comparison (optional `original_ticket_number`, `related_ticket_number`, `conjunction_ticket_numbers`)","output":"Discrepancies with severity and type (includes `UNMATCHED_EXCHANGE`, `CONJUNCTION_SET_MISMATCH`)\nSummary with `currencies_present` (multi-currency HOT awareness)\nCommission / amount compares only when agency and HOT transaction currencies match (no silent IROE/ICER FX)","status":"Implemented","purpose":"Matches agency booking records against BSP HOT files (DISH Rev 23), validates commission rates, identifies discrepancies (missing records, duplicates, amount/commission/currency mismatches, unmatched ADM/ACM, exchange/conjunction cross-refs), and flags issues before remittance deadline.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.2":{"id":"7.2","summary":"Processes ARC IAR weekly billing, validates commission rates against airline contracts, flags pricing/commission errors","className":"ARCReconciliation","input":"`iar_records` -- ARC IAR records (document number, amounts, commission, transaction type, settlement week, ADM issue dates)\n`agency_records` -- agency-side records for comparison","output":"Matched/unmatched records, discrepancies with severity, ADM dispute window warnings","status":"Implemented","purpose":"Processes ARC IAR (Interactive Agent Reporting) weekly billing, validates commission rates against airline contracts, flags pricing/commission errors, and manages ADM/ACM disputes within the 15-day window.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.3":{"id":"7.3","summary":"Commission agreement management, rate validation, incentive calculation","className":"CommissionManagementAgent","input":"`operation` -- `'registerAgreement' | 'getRate' | 'validateCommission' | 'calculateIncentive' | 'listAgreements'`\nAgreement data: agent ID, airline, type, rate, basis (percent/flat per ticket/segment), fare basis patterns, validity dates, minimum tickets\nValidation: claimed rate vs expected rate\nIncentive: period, ticket count, total fare","output":"`agreement?` -- registered agreement\n`rate?` -- applicable commission rate\n`validation?` -- match/overstated/understated status with variance\n`incentive?` -- earned incentive amount, threshold met flag","status":"Implemented","purpose":"Commission agreement management: register agreements (override, incentive, backend, net fare, standard), look up rates by airline/fare basis, validate claimed commission, and calculate incentive earnings.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.4":{"id":"7.4","summary":"Placeholder -- not yet implemented. Requires domain input on interline prorate methodology","className":"InterlineSettlementAgent","status":"Coming Soon (stub)","purpose":"Requires domain input on interline prorate methodology and SIS (Simplified Interline Settlement) billing rules before implementation can proceed.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"7.5":{"id":"7.5","summary":"Aggregates transaction data into reports (revenue by route, margin analysis, unused tickets, etc.)","className":"FinancialReportingAgent","input":"`type` -- report type (9 report types available)\n`period` -- date range\n`filters?` -- airlines, agents, corporate IDs, currencies, minimum amount\n`groupBy?` -- grouping dimensions\n`records` -- financial records (ticket, refund, ADM, ACM, commission, fee)\n`currency?` -- reporting currency","output":"Report line items with revenue, cost, commission, net per group\nReport totals","status":"Implemented","purpose":"Generates financial reports: revenue by route/agent/corporate client, margin analysis, cost tracking, commission summary, spend by supplier, unused ticket value, and settlement summary.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.6":{"id":"7.6","summary":"Coupon lift recording, revenue recognition, uplift/deferred revenue reporting","className":"RevenueAccountingAgent","input":"`operation` -- `'recordLift' | 'recognizeRevenue' | 'getUpliftReport' | 'getDeferredRevenue' | 'recordVoid' | 'recordRefund'`\nLift data: ticket number, coupon number, flight details, fare amount\nReport parameters: date range","output":"Lift records, revenue recognition results, uplift reports (by route/cabin with average yield), deferred revenue reports","status":"Implemented","purpose":"Coupon lift tracking and revenue recognition: record lifted coupons, recognize revenue per flight, generate uplift reports (by route, by cabin), track deferred revenue from open coupons, and handle voids/refunds.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.1":{"id":"8.1","summary":"Stores/retrieves traveler preferences, documents, loyalty programs. Applies profiles to PNRs via SSR injection","className":"TravelerProfileAgent","input":"`operation` -- `'get' | 'create' | 'update' | 'apply_to_pnr' | 'search'`\nProfile data: name, DOB, nationality, passport, loyalty numbers, seat/meal preference, contact info, corporate/employee ID, department, cost center\nPNR application: GDS system, segments for APIS generation","output":"`profile?` -- traveler profile record\n`profiles?` -- search results\nPNR application: generated SSR/OSI commands","status":"Implemented","purpose":"Traveler preferences, identity documents, loyalty programs, and PNR prefill. CRUD operations plus apply-to-PNR for generating SSR/APIS commands.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.2":{"id":"8.2","summary":"Corporate travel policy enforcement, negotiated fares, booking validation","className":"CorporateAccountAgent","input":"`operation` -- `'get_account' | 'create_account' | 'update_account' | 'validate_booking' | 'get_policy' | 'list_accounts' | 'get_preferred_suppliers'`\nAccount data: company name, IATA number, travel policy, negotiated fares, contact info\nBooking validation: segments, cabin, fare amount, advance days","output":"`account?` -- corporate account record\n`accounts?` -- account list\n`validation?` -- policy violations (hard/soft) with details\n`policy?` -- travel policy rules\n`suppliers?` -- preferred suppliers","status":"Implemented","purpose":"Corporate travel policy management, negotiated fare lookup, and booking validation against policy rules (cabin limits, fare ceilings, advance booking, preferred/blacklisted airlines).","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.3":{"id":"8.3","summary":"PNR quality checks, ticketing deadline monitoring, duplicate/passive detection","className":"MidOfficeAgent","input":"`trigger` -- `'scheduled_sweep' | 'pnr_created' | 'ticket_deadline_approaching' | 'queue_pending' | 'manual_review_request'`\n`pnrs` -- PNR records with segments, deadlines, APIS/contact/FOP flags\n`current_datetime?` -- ISO timestamp (compared as Zulu)","output":"Per-PNR issues with severity (urgent/high/medium/low) and issue codes\nSummary counts","status":"Implemented","purpose":"PNR quality checks and ticketing deadline monitoring. Scans PNRs for 10 issue types: TTL urgent/approaching, missing segment status, missing APIS, missing contact/FOP, duplicate PNR, passive segment, policy violation, married segment incomplete.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.4":{"id":"8.4","summary":"Aggregates transaction data into reports (booking volume, revenue, top routes, policy compliance)","className":"ReportingAgent","input":"`report_type` -- report type\n`date_from`, `date_to` -- date range\n`filters?` -- corporate ID, agent, airline, department, currency\n`transactions` -- transaction records (ticket, amounts, airline, dates, in-policy flag, used flag)","output":"Report rows grouped by the relevant dimension\nSummary totals","status":"Implemented","purpose":"Transaction aggregation and report generation across 9 report types: booking volume, revenue summary, top routes, agent productivity, policy compliance, spend by traveler/department/supplier, unused tickets.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.5":{"id":"8.5","summary":"Locates travelers in active itineraries during disruptions with destination risk assessment","className":"DutyCareAgent","input":"`operation` -- `'locate_travelers' | 'get_traveler_itinerary' | 'assess_destination_risk' | 'mark_accounted_for'`\nItineraries: traveler ID, segments with dates/times/status\nRisk: country code\nAccountability: traveler ID","output":"`locatedTravelers?` -- current location, status (IN_TRANSIT/AT_DESTINATION/DEPARTED/UNKNOWN), accounted-for flag\n`itinerary?` -- full traveler itinerary\n`risk?` -- country risk level (low/medium/high/critical) with notes","status":"Implemented","purpose":"Traveler location tracking, destination risk assessment, and accountability management for corporate duty-of-care obligations.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.1":{"id":"9.1","summary":"Coordinates multi-agent workflows as a single callable pipeline (search_to_price, book_to_ticket, full_booking, etc.)","className":"OrchestratorAgent","input":"`workflow` -- workflow name\n`input` -- workflow input data\n`options?` -- `stop_on_error?`, `timeout_ms?`","output":"`workflow` -- workflow name\n`status` -- `'completed' | 'failed' | 'partial'`\n`steps` -- per-step results (agent ID, status, duration, output/error)\n`total_duration_ms`\n`final_output?` -- last step output","usage":"Accepts injectable `StepExecutor` for testing without real agent imports. Then call initialize() and execute({ data }).","status":"Implemented","purpose":"Multi-agent workflow coordination. Defines named workflows (search-to-price, book-to-ticket, full booking, exchange flow, refund flow) as step sequences. Supports conditional steps, parallel execution, error handling (stop/skip/continue), and pipeline building."},"9.2":{"id":"9.2","summary":"RAG over travel knowledge base with BM25 relevance scoring and optional hybrid scoring via injectable EmbeddingProvider","className":"KnowledgeAgent","input":"`operation` -- `'query' | 'index_document' | 'list_topics' | 'get_document'`\nQuery: query string, topic filter, max results\nIndex: document ID, title, content, tags, topic","output":"`results?` -- ranked results with relevance score, excerpt, full content\n`document?` -- specific document\n`topics?` -- available topic list\n`query_time_ms?`","status":"Implemented","purpose":"RAG (Retrieval-Augmented Generation) over the travel knowledge base. Indexes documents by topic, supports BM25 + vector hybrid search with injectable embedding provider.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.3":{"id":"9.3","summary":"Tracks agent health, API latency, error rates, SLA compliance","className":"MonitoringAgent","input":"`operation` -- `'record_metric' | 'get_health' | 'list_alerts' | 'acknowledge_alert' | 'get_sla_report'`\nMetric: agent ID, metric type (latency_ms/error/success/timeout), value\nAlert: alert ID for acknowledgment","output":"`health?` -- agent health (status, p50/p95 latency, error rate, total calls)\n`alerts?` -- alert list with severity and fired timestamp\n`slaReport?` -- availability percent, p95 latency, error count","status":"Implemented","purpose":"Agent health monitoring: latency tracking (p50/p95), error rates, SLA compliance reporting. Records metrics, fires alerts on threshold violations, supports alert acknowledgment.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.4":{"id":"9.4","summary":"Audit trail, PII redaction, GDPR/PCI/IATA compliance","className":"AuditAgent","input":"`operation` -- `'log_event' | 'query_audit_log' | 'flag_compliance_issue' | 'get_compliance_report' | 'redact_pii'`\nEvent: type (agent_decision, data_access, booking_created, etc.), agent ID, user/session ID, payload\nCompliance: issue type, description, severity, affected records","output":"`entry?` -- audit log entry with hash, PII redaction flag, retention days\n`entries?` -- query results\n`issue?` -- flagged compliance issue\n`report?` -- compliance report (events with PII, redaction counts, open issues by severity)\n`redactedPayload?` -- PII-redacted data","status":"Implemented","purpose":"Audit trail logging with SHA-256 payload hashing, PII redaction (credit cards, passports, emails, phone numbers, DOB), GDPR/PCI/IATA compliance issue flagging, and compliance reporting.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.5":{"id":"9.5","summary":"Manages third-party agent extensions and capability discovery","className":"PluginManagerAgent","input":"`operation` -- `'register_plugin' | 'unregister_plugin' | 'list_plugins' | 'get_plugin' | 'discover_capabilities' | 'enable_plugin' | 'disable_plugin'`\nPlugin data: name, version, description, author, capabilities, agent IDs, metadata","output":"`plugin?` -- plugin record\n`plugins?` -- plugin list\n`capabilities?` -- capability-to-plugin mapping\n`message?` -- operation result message","status":"Implemented","purpose":"Third-party agent extension management: register/unregister plugins, enable/disable, capability discovery, and plugin metadata management.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.6":{"id":"9.6","summary":"Aggregates agent execution metrics from the EventStore within a given time window. Identifies degraded agents","className":"PerformanceAuditAgent","status":"Implemented","purpose":"Aggregates agent execution metrics from the EventStore within a given time window and identifies degraded agents. Read-only -- no side effects.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"9.7":{"id":"9.7","summary":"Analyses routing decisions and outcomes from the EventStore within a given time window","className":"RoutingAuditAgent","status":"Implemented","purpose":"Analyses routing decisions and outcomes from the EventStore within a given time window. Read-only -- no side effects.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"9.8":{"id":"9.8","summary":"Accepts performance and routing audit reports and produces deterministic recommendations","className":"RecommendationAgent","status":"Implemented","purpose":"Accepts performance and routing audit reports and produces deterministic recommendations. Read-only -- no side effects.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"9.9":{"id":"9.9","summary":"Queries EventStore events, computes metrics against configurable thresholds, and produces alerts","className":"AlertAgent","status":"Implemented","purpose":"Queries EventStore events, computes metrics against configurable thresholds, and produces alerts. Read-only -- no side effects.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"20.1":{"id":"20.1","summary":"Multi-source hotel availability search across GDS hotel segments, direct APIs, and channel manager feeds","className":"HotelSearchAggregatorAgent","input":"`destination` -- city name, airport code, or coordinates\n`checkIn` -- ISO date string (YYYY-MM-DD)\n`checkOut` -- ISO date string (YYYY-MM-DD)\n`rooms` -- number of rooms needed\n`adults` -- number of adult guests per room\n`children?` -- number of child guests per room\n`starRating?` -- minimum star rating filter\n`maxRatePerNight?` -- maximum nightly rate filter (decimal string)\n`currency?` -- ISO 4217 currency for rate filtering/display\n`rateType?` -- rate type filter\n`chainPreference?` -- chain code (e.g., `\"MC\"` for Marriott)\n`timeoutMs?` -- per-adapter timeout in milliseconds (default: 5000)\n`adapterIds?` -- specific adapter IDs to query (all if omitted)","output":"`properties` -- raw hotel results from all sources (NOT deduplicated)\n`totalResults` -- total result count across all adapters\n`adapterResults` -- per-adapter summary (ID, name, count, response time, timeout/error)\n`partialResults` -- true if some adapters timed out or errored\n`searchId` -- unique search ID for tracing","usage":"const agent = new HotelSearchAggregatorAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: {\n    destination: 'New York',\n    checkIn: '2026-06-01',\n    checkOut: '2026-06-03',\n    rooms: 1,\n    adults: 2,\n  },\n});\n// result.data.totalResults => 45\n// result.data.partialResults => false","status":"Implemented","purpose":"Multi-source hotel availability search across GDS hotel segments, direct APIs (Amadeus Hotel, Hotelbeds, Duffel Stays), and channel manager feeds. Returns raw, unmerged results from all connected sources. Supports injectable `HotelSourceAdapter` for plugging in custom sources."},"20.2":{"id":"20.2","summary":"Identifies duplicate properties from multi-source results and merges them into canonical records","className":"PropertyDeduplicationAgent","input":"`properties` -- raw hotel results from Agent 20.1\n`thresholds?` -- custom merge thresholds\n`autoMerge` -- score above which properties are auto-merged (default: 0.85)\n`review` -- score above which properties are flagged for review (default: 0.65)","output":"`canonical` -- canonical property records (one per physical property)\n`mergeLog` -- full audit trail of merge/separate decisions (property IDs, score, decision type, score breakdown)\n`stats` -- summary (input count, output count, auto-merged, review-flagged, separated)","usage":"const agent = new PropertyDeduplicationAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: { properties: rawResults },\n});\n// result.data.stats.inputCount => 45\n// result.data.stats.outputCount => 28\n// result.data.stats.autoMerged => 12","status":"Implemented","purpose":"Takes raw multi-source hotel results from Agent 20.1 and identifies duplicate properties (40-60% of multi-source results are duplicates). Merges them into canonical property records using weighted scoring: Jaro-Winkler name similarity (0.3), normalized address Levenshtein (0.2), Haversine coordinate proximity (0.25), chain code match (0.15), and star rating match (0.1)."},"20.3":{"id":"20.3","summary":"Standardizes hotel content (room types, amenity names, descriptions, photos) into a consistent OTAIP taxonomy","className":"ContentNormalizationAgent","input":"`properties` -- canonical property records from Agent 20.2","output":"`properties` -- normalized property content records, each containing:\n`canonicalId` -- pass-through from 20.2\n`property` -- original canonical property\n`normalizedRoomTypes` -- room types mapped to OTAIP taxonomy\n`normalizedAmenities` -- amenities mapped to OTAIP taxonomy\n`scoredPhotos` -- scored and categorized photos (category, quality score, primary flag)\n`unmappedRoomTypes` -- raw room types that could not be normalized\n`unmappedAmenities` -- raw amenity strings that could not be normalized\n`stats` -- totals for properties, mapped/unmapped room types, mapped/unmapped amenities","usage":"const agent = new ContentNormalizationAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: { properties: canonicalProperties },\n});\n// result.data.stats.totalRoomTypesMapped => 84\n// result.data.stats.totalAmenitiesUnmapped => 3","status":"Implemented","purpose":"Standardizes hotel content (room types, amenity names, photos) into a consistent OTAIP taxonomy for comparison and display. Maps raw room types from each source to the normalized taxonomy, merges amenities via union merge, and scores/categorizes photos."},"20.4":{"id":"20.4","summary":"Compares rates for the same canonical property across all sources, identifies best available rate, detects rate parity violations","className":"RateComparisonAgent","input":"`properties` -- canonical properties with source results containing rates\n`currency?` -- preferred currency for display (default: USD)\n`nights?` -- number of nights for the stay (default: 1)","output":"`comparisons` -- per-property rate comparison, each containing:\n`canonicalId` -- canonical property ID\n`propertyName` -- property name\n`rates` -- all rates sorted by total cost (lowest first), with full cost breakdown (room charges, mandatory fees, taxes, grand total)\n`bestByRateType` -- best rate per rate type\n`parity` -- rate parity analysis (at parity flag, lowest/highest source, spread percentage)\n`totalProperties` -- total properties compared\n`parityViolations` -- count of properties with rate parity violations","usage":"const agent = new RateComparisonAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: { properties: canonicalProperties, nights: 2 },\n});\n// result.data.comparisons[0].rates[0].totalCost.grandTotal => { amount: '289.00', currency: 'USD' }\n// result.data.parityViolations => 3","status":"Implemented","purpose":"Compares rates for the same canonical property across all sources, identifies best available rate per rate type, and detects rate parity violations (>2% spread between lowest and highest source). Includes ALL mandatory fees (resort fees, destination fees, taxes) in total cost breakdown."},"20.5":{"id":"20.5","summary":"Executes hotel bookings with three-layer confirmation code system (CRS, PMS, Channel)","className":"HotelBookingAgent","input":"`operation` -- `'book' | 'verify_rate' | 'get_booking'`\n`bookingRequest?` -- required for `book`/`verify_rate`:\n`canonicalPropertyId` -- from Agent 20.2\n`rateId` -- from Agent 20.4\n`source` -- hotel source to book through\n`checkIn` / `checkOut` -- ISO date strings\n`rooms` -- number of rooms\n`guest` -- guest details (name, email, phone, loyalty info)\n`paymentModel` -- payment model\n`specialRequests?` -- free text\n`bookingId?` -- required for `get_booking`","output":"`success` -- whether the operation succeeded\n`booking?` -- booking record (ID, three-layer confirmation codes, status, total charged, payment model, virtual card info, cancellation policy/deadline, guest, original request)\n`error?` -- error message if failed\n`rateChanged?` -- whether rate changed between search and booking\n`newRate?` -- new rate if changed","usage":"const agent = new HotelBookingAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: {\n    operation: 'book',\n    bookingRequest: {\n      canonicalPropertyId: 'canon-001',\n      rateId: 'rate-001',\n      source: 'amadeus_hotel',\n      checkIn: '2026-06-01',\n      checkOut: '2026-06-03',\n      rooms: 1,\n      guest: { firstName: 'John', lastName: 'Smith', email: 'john@example.com' },\n      paymentModel: 'merchant',\n    },\n  },\n});\n// result.data.booking?.confirmation.crs => \"CRS-ABC123\"","status":"Implemented","purpose":"Executes hotel bookings through the optimal source. Manages the full booking flow from rate verification through confirmation, including three-layer confirmation codes (CRS, PMS, channel). Supports VCN (Virtual Card Number) payment with dual folio requirements."},"20.6":{"id":"20.6","summary":"Post-booking changes: free modifications, date changes (cancel/rebook), cancellations with penalty calculation, no-show processing","className":"HotelModificationAgent","input":"`operation` -- `'modify' | 'cancel' | 'check_penalty' | 'process_no_show'`\n`bookingId` -- existing booking ID\n`modifications?` -- free modifications (guest name, bed type, smoking preference, special requests, accessibility needs, guest count)\n`dateChange?` -- new check-in / check-out dates (triggers cancel/rebook)\n`bookedAt?` -- booking timestamp for California 24hr rule check\n`cancellationPolicy?` -- current cancellation policy\n`checkInDate?` -- for deadline calculations\n`nightlyRate?` -- nightly rate from booking record (penalty base)","output":"`success` -- whether the operation succeeded\n`classification` -- `'free_modification' | 'cancel_rebook_required' | 'not_modifiable'`\n`isFreeMod` -- whether this is a free modification\n`penalty?` -- penalty calculation (amount, type, deadline, free window flag, California rule flag)\n`rebookRequired` -- whether a rebook is needed (for date changes)\n`newBookingId?` -- updated confirmation codes (for successful modifications)\n`message` -- error or status message","usage":"const agent = new HotelModificationAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: {\n    operation: 'cancel',\n    bookingId: 'BK-001',\n    cancellationPolicy: { type: 'free_cancellation', deadline: '2026-05-30T00:00:00Z' },\n    checkInDate: '2026-06-01',\n    bookedAt: '2026-04-01T10:00:00Z',\n  },\n});\n// result.data.classification => \"free_modification\"\n// result.data.penalty?.isWithinFreeWindow => true","status":"Implemented","purpose":"Handles post-booking changes: free modifications (guest name, bed type, special requests), date changes (which require cancel/rebook -- NOT modifications), cancellations with penalty calculation, and no-show processing. Enforces California 24-hour cancellation rule where applicable."},"20.7":{"id":"20.7","summary":"Cross-checks CRS-to-PMS booking data to detect discrepancies before guest arrival","className":"ConfirmationVerificationAgent","input":"`operation` -- `'verify' | 'check_pms_sync' | 'batch_verify'`\n`bookingId` -- booking ID to verify\n`confirmation` -- three-layer confirmation codes from booking\n`crsData` -- CRS-side booking data (confirmation code, guest name, dates, room type, rates, status)\n`pmsData?` -- PMS-side booking data (may be missing if PMS hasn't synced yet)\n`guest` -- guest details for name verification\n`hoursUntilCheckin?` -- hours until check-in (for escalation urgency)\n`batchBookingIds?` -- additional booking IDs (for `batch_verify`)","output":"`verified` -- whether verification passed with no critical issues\n`discrepancies` -- all detected discrepancies (field, CRS value, PMS value, severity, message)\n`escalationRequired` -- whether human/agent escalation is needed\n`escalationReasons` -- why escalation is needed (pms_code_missing, rate_mismatch, date_mismatch, guest_name_mismatch, waitlist_status, tentative_status, room_type_mismatch, multiple_discrepancies)\n`verifiedAt` -- verification timestamp\n`message` -- summary message","usage":"const agent = new ConfirmationVerificationAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: {\n    operation: 'verify',\n    bookingId: 'BK-001',\n    confirmation: { crs: 'CRS-ABC', pms: 'PMS-123', channel: 'CH-456' },\n    crsData: {\n      confirmationCode: 'CRS-ABC',\n      guestName: 'SMITH/JOHN',\n      checkIn: '2026-06-01',\n      checkOut: '2026-06-03',\n      roomType: 'King Standard',\n      nightlyRate: { amount: '189.00', currency: 'USD' },\n      totalRate: { amount: '378.00', currency: 'USD' },\n      status: 'confirmed',\n    },\n    guest: { firstName: 'John', lastName: 'Smith' },\n  },\n});\n// result.data.verified => true\n// result.data.discrepancies.length => 0","status":"Implemented","purpose":"Cross-checks CRS and PMS booking data to detect discrepancies before guest arrival. Escalates missing PMS codes, waitlist/tentative status, rate/date mismatches. PMS sync can take 1-4 hours; delays beyond 24 hours trigger escalation."},"20.8":{"id":"20.8","summary":"Thin typed wrapper around Hotelbeds Activities search for route→fill orchestration and product-layer activity_search mapping.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"20.9":{"id":"20.9","summary":"Thin typed wrapper around Hotelbeds Transfers search for route→fill orchestration.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."}}}</script>
+  <script id="graph-data" type="application/json">{"graph":{"generated_by":"scripts/generate-manifest.ts","total_nodes":77,"total_edges":27,"nodes":[{"id":"0.1","name":"Airport/City Code Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/reference/src/airport-code-resolver/index.ts"},{"id":"0.2","name":"Airline Code & Alliance Mapper","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/reference/src/airline-code-mapper/index.ts"},{"id":"0.3","name":"Fare Basis Code Decoder","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/reference/src/fare-basis-decoder/index.ts"},{"id":"0.4","name":"Class of Service Mapper","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/class-of-service-mapper/index.ts"},{"id":"0.5","name":"Equipment Type Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/equipment-type-resolver/index.ts"},{"id":"0.6","name":"Currency & Tax Code Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/currency-tax-resolver/index.ts"},{"id":"0.7","name":"Country Regulatory Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/country-regulatory-resolver/index.ts"},{"id":"1.1","name":"Availability Search","stage":"search","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/search/src/availability-search/index.ts"},{"id":"1.2","name":"Schedule Lookup","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/schedule-lookup/index.ts"},{"id":"1.3","name":"Connection Builder","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/connection-builder/index.ts"},{"id":"1.4","name":"Fare Shopping","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/fare-shopping/index.ts"},{"id":"1.5","name":"Ancillary Shopping","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/ancillary-shopping/index.ts"},{"id":"1.6","name":"Multi-Source Aggregator","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/multi-source-aggregator/index.ts"},{"id":"1.7","name":"Hotel & Car Search","stage":"search","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/search/src/hotel-car-search/index.ts"},{"id":"1.8","name":"AI Travel Advisor","stage":"search","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/search/src/ai-travel-advisor/index.ts"},{"id":"1.9","name":"Offer Evaluator","stage":"core","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/core/src/agents/shopping/offer-evaluator/index.ts"},{"id":"2.1","name":"Fare Rule Agent","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/pricing/src/fare-rule-agent/index.ts"},{"id":"2.2","name":"Fare Construction","stage":"pricing","version":"0.2.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/pricing/src/fare-construction/index.ts"},{"id":"2.3","name":"Tax Calculation","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/pricing/src/tax-calculation/index.ts"},{"id":"2.4","name":"Offer Builder","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/pricing/src/offer-builder/index.ts"},{"id":"2.5","name":"Corporate Policy Validation","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/pricing/src/corporate-policy-validation/index.ts"},{"id":"2.6","name":"Dynamic Pricing","stage":"pricing","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/pricing/src/dynamic-pricing/index.ts"},{"id":"2.7","name":"Revenue Management","stage":"pricing","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/pricing/src/revenue-management/index.ts"},{"id":"3.1","name":"GDS/NDC Router","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/booking/src/gds-ndc-router/index.ts"},{"id":"3.2","name":"PNR Builder","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/booking/src/pnr-builder/index.ts"},{"id":"3.3","name":"PNR Validation","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/pnr-validation/index.ts"},{"id":"3.4","name":"Queue Management","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/queue-management/index.ts"},{"id":"3.5","name":"API Abstraction","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/api-abstraction/index.ts"},{"id":"3.6","name":"Order Management","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/order-management/index.ts"},{"id":"3.7","name":"Payment Processing","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/payment-processing/index.ts"},{"id":"3.8","name":"PNR Retrieval","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/booking/src/pnr-retrieval/index.ts"},{"id":"4.1","name":"Ticket Issuance","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/ticketing/src/ticket-issuance/index.ts"},{"id":"4.2","name":"EMD Management","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/emd-management/index.ts"},{"id":"4.3","name":"Void Agent","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/void-agent/index.ts"},{"id":"4.4","name":"Itinerary Delivery","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/itinerary-delivery/index.ts"},{"id":"4.5","name":"Document Verification","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/document-verification/index.ts"},{"id":"5.1","name":"Change Management","stage":"exchange","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/exchange/src/change-management/index.ts"},{"id":"5.2","name":"Exchange/Reissue","stage":"exchange","version":"0.2.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/exchange/src/exchange-reissue/index.ts"},{"id":"5.3","name":"Involuntary Rebook","stage":"exchange","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/exchange/src/involuntary-rebook/index.ts"},{"id":"5.4","name":"Disruption Response","stage":"exchange","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/exchange/src/disruption-response/index.ts"},{"id":"5.5","name":"Self-Service Rebooking","stage":"exchange","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/exchange/src/self-service-rebooking/index.ts"},{"id":"5.6","name":"Waitlist Management","stage":"exchange","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/exchange/src/waitlist-management/index.ts"},{"id":"6.1","name":"Refund Processing","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/refund-processing/index.ts"},{"id":"6.2","name":"ADM Prevention","stage":"settlement","version":"0.2.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/adm-prevention/index.ts"},{"id":"6.3","name":"ADM/ACM Processing","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/adm-acm-processing/index.ts"},{"id":"6.4","name":"Customer Communication","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/customer-communication/index.ts"},{"id":"6.5","name":"Feedback & Complaint","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/feedback-complaint/index.ts"},{"id":"6.6","name":"Loyalty Mileage","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/loyalty-mileage/index.ts"},{"id":"7.1","name":"BSP Reconciliation","stage":"reconciliation","version":"0.2.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/bsp-reconciliation/index.ts"},{"id":"7.2","name":"ARC Reconciliation","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/arc-reconciliation/index.ts"},{"id":"7.3","name":"Commission Management","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/commission-management/index.ts"},{"id":"7.4","name":"Interline Settlement","stage":"reconciliation","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/reconciliation/src/interline-settlement/index.ts"},{"id":"7.5","name":"Financial Reporting","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/financial-reporting/index.ts"},{"id":"7.6","name":"Revenue Accounting","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/revenue-accounting/index.ts"},{"id":"8.1","name":"Traveler Profile","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/traveler-profile/index.ts"},{"id":"8.2","name":"Corporate Account","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/corporate-account/index.ts"},{"id":"8.3","name":"Mid-Office Automation","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/mid-office/index.ts"},{"id":"8.4","name":"Reporting & Analytics","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/reporting/index.ts"},{"id":"8.5","name":"Duty of Care","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/duty-of-care/index.ts"},{"id":"9.1","name":"Orchestrator","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/orchestrator/index.ts"},{"id":"9.2","name":"Knowledge Retrieval","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/knowledge/index.ts"},{"id":"9.3","name":"Monitoring & Alerting","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/monitoring/index.ts"},{"id":"9.4","name":"Audit & Compliance","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/audit/index.ts"},{"id":"9.5","name":"Plugin Manager","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/plugin-manager/index.ts"},{"id":"9.6","name":"Performance Audit","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/performance-audit/index.ts"},{"id":"9.7","name":"Routing Audit","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/routing-audit/index.ts"},{"id":"9.8","name":"Recommendation","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/recommendation/index.ts"},{"id":"9.9","name":"Alert","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/alert/index.ts"},{"id":"20.1","name":"Hotel Search Aggregator","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/hotel-search/index.ts"},{"id":"20.2","name":"Property Deduplication","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/property-dedup/index.ts"},{"id":"20.3","name":"Hotel Content Normalization","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/content-normalization/index.ts"},{"id":"20.4","name":"Hotel Rate Comparison","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/rate-comparison/index.ts"},{"id":"20.5","name":"Hotel Booking","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/hotel-booking/index.ts"},{"id":"20.6","name":"Hotel Modification & Cancellation","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/hotel-modification/index.ts"},{"id":"20.7","name":"Confirmation Verification","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/confirmation-verification/index.ts"},{"id":"20.8","name":"Activity Search","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/activity-search/index.ts"},{"id":"20.9","name":"Transfer Search","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/transfer-search/index.ts"}],"edges":[{"source":"1.1","target":"1.4","kind":"workflow","label":"search_to_price"},{"source":"1.4","target":"2.1","kind":"workflow","label":"search_to_price"},{"source":"2.1","target":"2.2","kind":"workflow","label":"search_to_price"},{"source":"2.2","target":"2.3","kind":"workflow","label":"search_to_price"},{"source":"3.3","target":"3.1","kind":"workflow","label":"book_to_ticket"},{"source":"3.1","target":"3.2","kind":"workflow","label":"book_to_ticket"},{"source":"3.2","target":"4.1","kind":"workflow","label":"book_to_ticket"},{"source":"1.1","target":"1.4","kind":"workflow","label":"full_booking"},{"source":"1.4","target":"2.1","kind":"workflow","label":"full_booking"},{"source":"2.1","target":"2.2","kind":"workflow","label":"full_booking"},{"source":"2.2","target":"2.3","kind":"workflow","label":"full_booking"},{"source":"2.3","target":"3.3","kind":"workflow","label":"full_booking"},{"source":"3.3","target":"3.1","kind":"workflow","label":"full_booking"},{"source":"3.1","target":"3.2","kind":"workflow","label":"full_booking"},{"source":"3.2","target":"4.1","kind":"workflow","label":"full_booking"},{"source":"5.1","target":"5.2","kind":"workflow","label":"exchange_flow"},{"source":"6.1","target":"6.2","kind":"workflow","label":"refund_flow"},{"source":"1.1","target":"0.1","kind":"package","label":"@otaip/agents-search → @otaip/agents-reference"},{"source":"2.1","target":"0.1","kind":"package","label":"@otaip/agents-pricing → @otaip/agents-reference"},{"source":"3.1","target":"0.1","kind":"package","label":"@otaip/agents-booking → @otaip/agents-reference"},{"source":"3.1","target":"1.1","kind":"package","label":"@otaip/agents-booking → @otaip/agents-search"},{"source":"3.1","target":"2.1","kind":"package","label":"@otaip/agents-booking → @otaip/agents-pricing"},{"source":"4.1","target":"3.1","kind":"package","label":"@otaip/agents-ticketing → @otaip/agents-booking"},{"source":"5.1","target":"1.1","kind":"package","label":"@otaip/agents-exchange → @otaip/agents-search"},{"source":"5.1","target":"4.1","kind":"package","label":"@otaip/agents-exchange → @otaip/agents-ticketing"},{"source":"6.1","target":"4.1","kind":"package","label":"@otaip/agents-settlement → @otaip/agents-ticketing"},{"source":"7.1","target":"0.1","kind":"package","label":"@otaip/agents-reconciliation → @otaip/agents-reference"}],"package_deps":[{"from_package":"@otaip/agents-search","to_package":"@otaip/agents-reference","from_stage":"search","to_stage":"reference"},{"from_package":"@otaip/agents-pricing","to_package":"@otaip/agents-reference","from_stage":"pricing","to_stage":"reference"},{"from_package":"@otaip/agents-booking","to_package":"@otaip/agents-reference","from_stage":"booking","to_stage":"reference"},{"from_package":"@otaip/agents-booking","to_package":"@otaip/agents-search","from_stage":"booking","to_stage":"search"},{"from_package":"@otaip/agents-booking","to_package":"@otaip/agents-pricing","from_stage":"booking","to_stage":"pricing"},{"from_package":"@otaip/agents-ticketing","to_package":"@otaip/agents-booking","from_stage":"ticketing","to_stage":"booking"},{"from_package":"@otaip/agents-exchange","to_package":"@otaip/agents-search","from_stage":"exchange","to_stage":"search"},{"from_package":"@otaip/agents-exchange","to_package":"@otaip/agents-ticketing","from_stage":"exchange","to_stage":"ticketing"},{"from_package":"@otaip/agents-settlement","to_package":"@otaip/agents-ticketing","from_stage":"settlement","to_stage":"ticketing"},{"from_package":"@otaip/agents-reconciliation","to_package":"@otaip/agents-reference","from_stage":"reconciliation","to_stage":"reference"}]},"docs":{"0.1":{"id":"0.1","summary":"Resolves IATA/ICAO airport and city codes to canonical airport records with multi-airport city awareness and historical code handling","className":"AirportCodeResolver","input":"`code` -- IATA 3-letter, ICAO 4-letter, city code, or airport name\n`code_type?` -- `'iata' | 'icao' | 'city' | 'name' | 'auto'` (auto-detected if omitted)\n`include_metro?` -- return all airports in a metro/city code (default: true)\n`include_decommissioned?` -- resolve retired/reassigned codes (default: false)","output":"`resolved_airport` -- canonical airport record (IATA, ICAO, name, city, country, timezone, lat/lon, type, status)\n`metro_airports` -- list of airports in the same metro area\n`match_confidence` -- 0-1 confidence score\n`stale_data?` -- true when dataset is older than 30 days\n`suggestion?` -- fuzzy match suggestion when code not found","usage":"const agent = new AirportCodeResolver();\nawait agent.initialize();\nconst result = await agent.execute({ data: { code: 'JFK', code_type: 'iata' } });\n// result.data.resolved_airport.name => \"John F Kennedy International Airport\"","status":"Implemented","purpose":"Resolves IATA/ICAO airport and city codes to canonical airport records with multi-airport city awareness, fuzzy name matching, and historical code handling."},"0.2":{"id":"0.2","summary":"Resolves IATA/ICAO airline designator codes to canonical airline records with alliance membership mapping and codeshare partner networks","className":"AirlineCodeMapper","input":"`code` -- IATA 2-letter, ICAO 3-letter, or airline name\n`code_type?` -- `'iata' | 'icao' | 'name' | 'auto'`\n`include_codeshares?` -- include codeshare partners (default: false)\n`include_defunct?` -- include ceased-operations airlines (default: false)","output":"`airline` -- canonical airline record (codes, name, callsign, country, alliance, hubs, status)\n`codeshare_partners` -- partner airline list with relationship type\n`match_confidence` -- 0-1 confidence score","usage":"const agent = new AirlineCodeMapper();\nawait agent.initialize();\nconst result = await agent.execute({ data: { code: 'UA', include_codeshares: true } });\n// result.data.airline.name => \"United Airlines\"","status":"Implemented"},"0.3":{"id":"0.3","summary":"Decodes ATPCO-standard fare basis codes into human-readable components including cabin class, fare restrictions, advance purchase requirements, and penalty information","className":"FareBasisDecoder","input":"`fare_basis` -- ATPCO fare basis code (max 15 chars, e.g., `\"YOW3M1\"`, `\"TLXP14NR\"`)\n`carrier?` -- IATA airline code for carrier-specific decoding","output":"`decoded` -- parsed components (primary code, cabin class, fare type, season, day-of-week, advance purchase, min/max stay, penalties, ticket designator)\n`match_confidence` -- 1.0 = fully decoded, 0.5-0.9 = partial\n`unparsed_segments` -- parts that could not be decoded","usage":"const agent = new FareBasisDecoder();\nawait agent.initialize();\nconst result = await agent.execute({ data: { fare_basis: 'Y26NR' } });\n// result.data.decoded.cabin_class => \"economy\"","status":"Implemented"},"0.4":{"id":"0.4","summary":"Maps single-letter booking class codes to cabin class, fare family, upgrade eligibility, and loyalty program earning rates","className":"ClassOfServiceMapper","input":"`booking_class` -- single letter A-Z\n`carrier` -- IATA 2-letter airline code (required -- meanings are carrier-specific)\n`include_loyalty?` -- include loyalty earning rates (default: false)","output":"`mapping` -- cabin class, brand name, fare family, upgrade eligibility/type, same-day change, seat selection, refundable, priority level, loyalty earning\n`match_confidence` -- 1.0 = carrier-specific, 0.7 = IATA default, 0 = unknown","usage":"const agent = new ClassOfServiceMapper();\nawait agent.initialize();\nconst result = await agent.execute({ data: { booking_class: 'J', carrier: 'UA', include_loyalty: true } });\n// result.data.mapping.cabin_class => \"business\"","status":"Implemented","purpose":"Maps single-letter booking class codes to cabin class, fare family, upgrade eligibility, and loyalty program earning rates. Booking classes are carrier-specific."},"0.5":{"id":"0.5","summary":"Resolves IATA aircraft equipment codes to structured equipment data","className":"EquipmentTypeResolver","input":"`operation` -- `'resolve' | 'getSeatingConfig' | 'isWidebody' | 'getSimilarTypes'`\n`code` -- IATA equipment code (e.g., `\"789\"`, `\"320\"`)\n`cabin?` -- cabin code (`'F' | 'C' | 'W' | 'Y'`) for `getSeatingConfig`","output":"`equipment?` -- full equipment info (IATA/ICAO codes, manufacturer, family, body type, seats, range)\n`seatCount?` -- seat count for specific cabin\n`isWidebody?` -- boolean\n`similarTypes?` -- IATA codes of similar aircraft","usage":"const agent = new EquipmentTypeResolver();\nawait agent.initialize();\nconst result = await agent.execute({ data: { operation: 'resolve', code: '789' } });\n// result.data.equipment.manufacturer => \"Boeing\"","status":"Implemented","purpose":"Resolves IATA aircraft equipment codes to structured equipment data including manufacturer, body type, typical seating, range, and max capacity."},"0.6":{"id":"0.6","summary":"Resolves ISO 4217 currency codes and IATA tax/surcharge codes used in airline pricing and ticketing","className":"CurrencyTaxResolver","input":"`code` -- ISO currency code or IATA tax code\n`code_type?` -- `'currency' | 'tax' | 'auto'`\n`country?` -- ISO 2-letter country code to filter tax applicability","output":"`currency` -- currency details (code, name, symbol, minor units, countries, active status)\n`tax` -- tax details (code, name, description, category, country, applies-to, percentage flag)\n`match_confidence` -- 0-1 confidence score","usage":"const agent = new CurrencyTaxResolver();\nawait agent.initialize();\nconst result = await agent.execute({ data: { code: 'USD' } });\n// result.data.currency.name => \"US Dollar\"","status":"Implemented"},"0.7":{"id":"0.7","summary":"APIS requirements, visa requirements, restriction levels. Static dataset -- must NOT be used as legal travel advice","className":"CountryRegulatoryResolver","input":"`operation` -- `'getAPISRequirements' | 'getVisaRequirement' | 'getRestrictionLevel'`\n`countryCode?` -- ISO 2-letter (for APIS and restriction)\n`nationalityCode?` -- ISO 2-letter (for visa)\n`destinationCode?` -- ISO 2-letter (for visa)","output":"`apis?` -- APIS requirements (required fields, advance submission hours)\n`visa?` -- visa requirement (type, max stay days)\n`restriction?` -- restriction level 1-4 with summary","usage":"const agent = new CountryRegulatoryResolver();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: { operation: 'getVisaRequirement', nationalityCode: 'US', destinationCode: 'GB' }\n});\n// result.data.visa.requirement => \"visa_free\"","status":"Implemented"},"1.1":{"id":"1.1","summary":"Queries distribution adapters in parallel, normalizes, deduplicates, filters, and sorts flight availability offers","className":"AvailabilitySearch","input":"`origin` -- origin airport/city IATA code\n`destination` -- destination airport/city IATA code\n`departure_date` -- ISO 8601 date\n`return_date?` -- ISO 8601 date for round-trip\n`passengers` -- `PassengerCount[]`\n`cabin_class?` -- `'economy' | 'premium_economy' | 'business' | 'first'`\n`direct_only?` -- only direct flights\n`max_connections?` -- 0-5\n`currency?` -- ISO 4217\n`max_results?` -- 1-200\n`sort_by?` -- `'price' | 'duration' | 'departure' | 'arrival' | 'connections'`\n`sort_order?` -- `'asc' | 'desc'`\n`sources?` -- specific adapter names to query","output":"`offers` -- deduplicated, filtered, sorted `SearchOffer[]`\n`total_raw_offers` -- count before deduplication\n`source_status` -- per-adapter query status (success, count, error, response time)\n`truncated` -- whether results were capped","usage":"new AvailabilitySearch(adapters: DistributionAdapter[]) Then call initialize() and execute({ data }).","status":"Implemented"},"1.2":{"id":"1.2","summary":"Looks up flight schedules with SSIM operating day parsing, codeshare detection, and connection discovery","className":"ScheduleLookup","input":"`origin` -- airport IATA code\n`destination` -- airport IATA code\n`date` -- ISO 8601 date\n`carrier?` -- filter by carrier IATA code\n`flight_number?` -- specific flight (requires carrier)\n`include_codeshares?` -- default: true\n`include_connections?` -- discover connecting options (default: false)","output":"`flights` -- `ScheduledFlight[]` (carrier, flight number, times, duration, schedule, codeshare info)\n`connections` -- `ConnectionOption[]` (two-leg connections with timing)\n`operates_on_date` -- whether any flights operate on the requested date","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.3":{"id":"1.3","summary":"Validates connections against MCT rules, scores connection quality, and checks interline agreements","className":"ConnectionBuilder","input":"`arriving_segment` -- `FlightSegment` (from `@otaip/core`)\n`departing_segment` -- `FlightSegment`\n`connection_airport` -- IATA 3-letter code\n`has_checked_bags?` -- affects MCT\n`is_interline?` -- different carriers","output":"`validation` -- MCT check result (valid, available/required minutes or null when unavailable, buffer, applied rule)\n`quality` -- connection quality score 0-1 with factor breakdown\n`interline` -- interline agreement check (if different carriers)\n`warnings` -- connection warnings","status":"Implemented","purpose":"Validates connections against MCT (Minimum Connecting Time) rules, scores connection quality, and checks interline agreements.\n\nMCT authority: **IATA SSIM Chapter 8** + **PSC Resolution 765** (`docs/knowledge-base/mct.md`). Curated rows live under `data/reference/mct/`. Resolution hierarchy: carrier override → airport+terminal → airport → **fail-closed** (no invented global/airport-constant table).","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.4":{"id":"1.4","summary":"Multi-source fare comparison with fare basis decoding, class mapping, branded fare family grouping, and passenger type pricing","className":"FareShopping","input":"`origin`, `destination`, `departure_date`, `passengers` -- same as availability search\n`cabin_class?`, `currency?`, `sources?` -- filters\n`decode_fare_basis?` -- decode fare basis codes (default: true)\n`group_by_fare_family?` -- group by basic/standard/flex/premium (default: true)","output":"`fares` -- `FareOffer[]` sorted by price, each with decoded fare basis, class info, fare family, passenger pricing\n`fare_families` -- grouped by family with cheapest/most expensive\n`total_fares` -- count\n`sources_queried` -- adapter names","usage":"new FareShopping(adapters: DistributionAdapter[]) Then call initialize() and execute({ data }).","status":"Implemented"},"1.5":{"id":"1.5","summary":"Searches ancillary offers (seats, bags, meals) across distribution adapters","className":"AncillaryShoppingAgent","input":"`segments` -- flight segments (origin, destination, flight number, date, carrier)\n`passengers` -- passenger references with type (ADT/CHD/INF)\n`pnrRef?` -- PNR reference\n`requestedCategories?` -- filter by category (BAGGAGE, SEAT, MEAL, etc.)","output":"`ancillaries` -- `AncillaryOffer[]` with RFIC/RFISC codes, pricing, availability\n`notSupportedByAdapter` -- true if no adapter configured\n`currency` -- pricing currency","status":"Implemented","purpose":"Searches for available ancillaries (baggage, seats, meals, lounge, Wi-Fi, priority) via an injectable adapter.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.6":{"id":"1.6","summary":"Deduplicates and normalizes flight results from multiple adapter sources","className":"MultiSourceAggregatorAgent","input":"`results` -- `AdapterSearchResult[]` (adapter name, flights, errors, response time)\n`deduplicationStrategy` -- `'keep_cheapest' | 'keep_all' | 'keep_first'`\n`rankBy` -- `'price' | 'duration' | 'stops'`\n`maxResults?` -- limit output count","output":"`flights` -- `NormalizedFlight[]` with sources, lowest price, all prices across adapters\n`totalRaw` -- raw count before dedup\n`totalAfterDedup` -- final count\n`adapterSummary` -- per-adapter stats","status":"Implemented","purpose":"Aggregates search results from multiple adapters with deduplication, price comparison, and ranking.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.7":{"id":"1.7","summary":"Stub agent for hotel and car rental search via distribution adapters","className":"HotelCarSearchAgent","input":"`operation` -- `'searchHotels' | 'searchCars'`\n`hotel?` -- hotel search params (destination, dates, rooms, adults, star rating, max rate)\n`car?` -- car search params (pickup/dropoff location and times, category, driver age)","output":"`hotelResults?` -- hotel offers with rate, room type, cancellation policy\n`carResults?` -- car offers with category, supplier, daily/total rate, features","status":"Implemented (adapter-dependent)","purpose":"Car rental search (and, pending a deferred car-only migration, hotel) via pluggable adapters. Returns empty results when no adapters configured.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.8":{"id":"1.8","summary":"Natural language travel query understanding with injectable LLM provider; parses user queries into structured search parameters","className":"AITravelAdvisorAgent","input":"`query` -- natural language travel query\n`travelerContext?` -- preferences (cabin, budget, preferred airlines, passenger counts)","output":"`searchParameters` -- extracted origin, destination, dates, trip type, cabin, passengers, flexible dates\n`summary` -- natural language summary of interpreted query\n`intent` -- `'flight_search' | 'hotel_search' | 'destination_recommendation' | 'price_check' | 'trip_planning' | 'unknown'`","usage":"new AITravelAdvisorAgent({ llmProvider, maxTokens?, temperature? }) Then call initialize() and execute({ data }).","status":"Implemented"},"1.9":{"id":"1.9","summary":"Stateless, deterministic scoring engine for flight offers with multi-dimensional scoring, hard filtering, and full audit trail (lives in @otaip/core)","className":"OfferEvaluatorAgent","input":"`offers` -- `EvaluatorOffer[]` with price, itinerary (segments, duration, connections)\n`constraints?` -- latest arrival, prefer direct, max connections, price ceiling, preferred/blacklisted carriers\n`profile?` -- `'BUSINESS_TIME_CRITICAL' | 'BUSINESS_PRICE_CONSTRAINED' | 'LEISURE' | 'CORPORATE_POLICY' | 'CUSTOM'`\n`weights?` -- custom scoring weights (time_buffer, price, connection_quality, journey_duration)","output":"Scored and ranked offers with structured explanation for LLM translation","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.1":{"id":"2.1","summary":"Parses ATPCO fare rules (categories 1-20) into human-readable structured format using curated tariff snapshot data","className":"FareRuleAgent","input":"`fare_basis` -- fare basis code\n`carrier` -- marketing carrier IATA code\n`origin` -- origin IATA code\n`destination` -- destination IATA code\n`travel_date?` -- ISO date for date-based rule filtering\n`categories?` -- specific ATPCO categories 1-50 (all if omitted)","output":"`rules` -- `FareRuleResult[]` with parsed categories, penalty summary, advance purchase, min/max stay, seasonality\n`total_rules` -- count of matched rules\n`valid_for_date` -- whether fare is valid for the specified travel date\n`in_blackout` -- whether travel date falls in a blackout period","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.2":{"id":"2.2","summary":"NUC x ROE fare construction with mileage validation, HIP/BHC/CTM checks, surcharges, and IATA rounding. All financial math uses decimal.js","className":"FareConstruction","input":"`journey_type` -- `'OW' | 'RT' | 'CT'` (one-way, round-trip, circle-trip)\n`components` -- fare components (origin, destination, carrier, fare basis, NUC amount)\n`selling_currency` -- ISO 4217 currency\n`point_of_sale?` -- country for IROE selection context\n`data_sources?` -- licensed `{ iroe, rounding_024d, mileage }` (required for a constructed fare)","output":"Success (`FareConstructionOutput`): `total_nuc`, `iroe` (alias `roe`), `local_amount` after 024d, `rounding_method` (`HX`|`NX`), published `mileage_checks`, HIP/BHC/CTM sketches, `audit_trail`\nOr `DomainInputRequired` when licensed data is missing","status":"Implemented","purpose":"NUC × IROE construction with published TPM/MPM, Resolution **024d** (HX/NX) rounding, and fail-closed HIP/BHC/CTM hooks. All financial math uses `decimal.js`.\n\nLicensed IROE / 024d / TPM-MPM data are **not** shipped in the package. Pass them via `data_sources`. Missing IROE, TPM, or 024d → `DomainInputRequired`. Haversine-as-TPM and banker's rounding are banned.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.3":{"id":"2.3","summary":"Per-segment tax computation with exemption engine, ~30 countries, ~50 tax codes, currency conversion. All financial math uses decimal.js","className":"TaxCalculation","input":"`segments` -- itinerary segments (origin/destination airports and countries, carrier, cabin class, base fare NUC)\n`passenger_type` -- `'adult' | 'child' | 'infant' | 'crew' | 'diplomatic'`\n`is_transit` -- whether transit/connection (\u003c 24h same ticket)\n`is_involuntary` -- whether involuntary reroute\n`total_base_fare_nuc` -- total base fare for percentage-based taxes\n`selling_currency` -- ISO 4217","output":"`taxes` -- `AppliedTax[]` (code, name, country, type, amounts, segment indices, interlineable, exempt status)\n`total_tax` -- total in selling currency\n`breakdown` -- by country, interlineable/non-interlineable totals\n`exemptions_applied` -- list of exemption reasons\n`segments_processed` -- count","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.4":{"id":"2.4","summary":"Builds priced offers with TTL management and optional persistence adapter","className":"OfferBuilderAgent","input":"`operation` -- `'buildOffer' | 'getOffer' | 'validateOffer' | 'markUsed' | 'expireOffer' | 'cleanExpired'`\n`buildInput?` -- segments, fare, taxes, ancillaries, passenger count, pricing source, TTL\n`offerId?` -- for get/validate/mark/expire operations\n`currentTime?` -- ISO timestamp override","output":"`offer?` -- full offer record with pricing breakdown, TTL, status\n`valid?` -- offer validity result\n`reason?` -- validation failure reason\n`cleanedCount?` -- number of expired offers cleaned","usage":"new OfferBuilderAgent({ persistence?: PersistenceAdapter }) Then call initialize() and execute({ data }).","status":"Implemented","purpose":"Builds, caches, validates, and manages pricing offers with TTL expiration. Supports in-memory or pluggable persistence."},"2.5":{"id":"2.5","summary":"Validates flight offers against corporate travel policies (cabin, budget, advance purchase)","className":"CorporatePolicyValidationAgent","input":"`offer` -- offer details (cabin, fare amount, carrier, fare basis, advance booking days, segments)\n`policy` -- corporate policy (cabin rules, fare rules, booking rules, bypass codes)\n`bypassCode?` -- authorization code to bypass soft violations","output":"`result` -- `'APPROVED' | 'SOFT_VIOLATION' | 'HARD_VIOLATION'`\n`violations` -- `PolicyViolation[]` with rule, severity, detail\n`bypassApplied` -- whether bypass was used","status":"Implemented","purpose":"Validates flight offers against corporate travel policies: cabin class limits, fare ceilings, blocked carriers, advance booking requirements. Supports bypass codes.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.6":{"id":"2.6","summary":"Placeholder -- not yet implemented. Requires revenue management integration","className":"DynamicPricingAgent","status":"Coming Soon (stub)","purpose":"Revenue management integration for dynamic fare adjustments. Requires revenue management integration before implementation can proceed.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"2.7":{"id":"2.7","summary":"Placeholder -- not yet implemented. Requires revenue management integration","className":"RevenueManagementAgent","status":"Coming Soon (stub)","purpose":"Revenue management system integration. Requires revenue management domain input before implementation can proceed.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"3.1":{"id":"3.1","summary":"Routes booking requests to the correct distribution channel based on carrier config, codeshare rules, and NDC capability","className":"GdsNdcRouter","input":"`segments` -- routing segments (marketing/operating carrier, origin, destination, flight number)\n`transaction_type` -- `'shopping' | 'booking' | 'ticketing' | 'servicing' | 'group' | 'corporate'` (aliases for matrix labels Shop / OrderCreate / Servicing|OrderChange|OrderCancel / Groups / Corporate)\n`vendor?` -- `'sabre' | 'amadeus' | 'duffel' | 'navitaire' | 'trippro' | 'airline_direct' | 'unknown'` (required for unambiguous matrix lookup)\n`plating_carrier?` -- when plating ≠ marketing/operating (DOMAIN_QUESTION on precedence)\n`capability_matrix?` -- inline KB CSV-shaped rows; preferred over airline→channel maps\n`capability_overrides?` -- per-carrier, per-transaction escape hatch when matrix cell is unknown\n`preferred_channel?` -- `'GDS' | 'NDC' | 'DIRECT'`\n`preferred_gds?` -- `'AMADEUS' | 'SABRE' | 'TRAVELPORT'`\n`include_fallbacks` -- whether to include fallback channels","output":"`routings` -- per-segment channel routing (primary channel, GDS system, NDC version, fallbacks, booking format); `domain_input_required` when matrix/override missing\n`unified_channel` -- whether all segments can use the same channel\n`recommended_channel` -- best channel for entire itinerary\n`gds_format` / `ndc_format` -- format translation stubs (`ndc_format` omitted when version unknown — never invents `21.3`)","status":"Implemented","purpose":"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`).","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.2":{"id":"3.2","summary":"Constructs GDS-ready PNR commands from normalized booking data. Supports Amadeus, Sabre, and Travelport syntax","className":"PnrBuilder","input":"`gds` -- `'AMADEUS' | 'SABRE' | 'TRAVELPORT'`\n`passengers` -- name, type, DOB, passport, gender, nationality, FOID\n`segments` -- carrier, flight, class, date, origin, destination, status\n`contacts` -- phone, email, type\n`ticketing` -- time limit, type\n`received_from` -- agent identifier\n`ssrs?` -- SSR elements (WCHR, VGML, DOCS, FOID, CTCE, CTCM, INFT)\n`osis?` -- OSI elements\n`is_group?` / `group_name?` -- group PNR support","output":"`gds` -- target GDS\n`commands` -- ordered `PnrCommand[]` with GDS command strings and descriptions\n`passenger_count`, `segment_count`, `is_group`, `infant_count`","status":"Implemented","purpose":"Constructs GDS-ready PNR commands from normalized booking data. Supports Amadeus, Sabre, and Travelport syntax including names, segments, contacts, ticketing, SSR/OSI elements, and group bookings.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.3":{"id":"3.3","summary":"Pre-ticketing validation -- 13 checks to catch errors before ADMs","className":"PnrValidation","input":"`record_locator` -- 6-char PNR\n`passengers` -- passenger data (name, type, DOB, nationality, passport)\n`segments` -- segment data (carrier, flight, status, class, international flag, married group)\n`contact?` -- phone/email\n`ticketing?` -- time limit, arranged status\n`fare?` -- fare data with advance purchase deadline\n`validation_date?` -- ISO date override","output":"`record_locator` -- PNR\n`checks` -- `ValidationCheck[]` (13 checks, each with pass/fail, severity, message)\n`valid` -- overall pass/fail\n`error_count`, `warning_count`","status":"Implemented","purpose":"Pre-ticketing validation with 13 checks to catch errors before ADMs: segment status, passenger data, APIS, ticketing deadline, fare consistency, and more.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.4":{"id":"3.4","summary":"GDS queue monitoring and processing -- priority assignment, categorization, action routing, and queue command generation","className":"QueueManagement","input":"`entries` -- queue items (record locator, GDS, queue number, entry type, deadline, remark)\n`current_time?` -- ISO timestamp for priority calculation\n`gds?` -- GDS system for command generation\n`queue_number?` -- queue to generate read commands for\n`travelport_host?` -- `'APOLLO' | 'GALILEO' | 'WORLDSPAN'` when `gds` is `TRAVELPORT`","output":"`results` -- processed items with priority, status, recommended action, target agent\n`commands?` -- GDS queue commands\n`summary` -- counts by priority (urgent/high/normal/low)","status":"Implemented","purpose":"GDS queue monitoring and processing: priority assignment, categorization, action routing, and queue command generation.\n\nTravelport place/list/remove commands are **per host** (Apollo / Galileo≡Travelport+ / Worldspan) from the public format-compare table — see `docs/knowledge-base/tmc-mid-office-ttl-queues.md`. TTL priority uses Zulu deadline-day urgency.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.5":{"id":"3.5","summary":"Universal HTTP client with circuit breaker, retry logic, timeout handling, rate limiting, and IATA error normalization","className":"ApiAbstraction","input":"`request` -- API request (provider ID, HTTP method, path, headers, body)\n`max_retries?` -- override retry count\n`timeout_ms?` -- override timeout\n`force?` -- skip circuit breaker check","output":"`response` -- API response (status, headers, body, duration, retries)\n`error` -- normalized error (category, original code, retryable flag)\n`circuit_breaker` -- circuit breaker status\n`rate_limit` -- rate limit status\n`success` -- boolean","usage":"new ApiAbstraction(handler?: RequestHandler) Then call initialize() and execute({ data }).","status":"Implemented","purpose":"Universal HTTP client with circuit breaker, retry logic, timeout handling, rate limiting, and IATA error normalization for GDS/NDC/payment providers."},"3.6":{"id":"3.6","summary":"Travel order lifecycle management -- create, modify, cancel, retrieve, and list orders with status tracking and transition validation","className":"OrderManagement","input":"`operation` -- `'createOrder' | 'modifyOrder' | 'cancelOrder' | 'getOrder' | 'listOrders'`\n`createOrder?` -- passenger, items, currency, source\n`modifyOrder?` -- order ID, updated items/details, reason\n`cancelOrder?` -- order ID, reason\n`getOrder?` / `listOrders?` -- retrieval/filtering","output":"`order?` -- order record with status, items, history\n`orders?` -- list of orders\n`operation`, `success`, `errorCode?`, `errorMessage?`","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.7":{"id":"3.7","summary":"PCI-safe payment instruction builder and transaction recorder. Validates forms of payment, builds GDS FOP strings -- never handles raw card numbers","className":"PaymentProcessing","input":"`operation` -- `'validateFOP' | 'buildPaymentInstruction' | 'recordPayment' | 'getPaymentRecord' | 'buildGDSFOPString'`\nOperation-specific data: FOP details (CC_TOKEN, BSP_CASH, AIRLINE_CREDIT, VOUCHER, UATP), amounts, references","output":"`validation?` -- FOP validation result\n`instruction?` -- payment instruction with GDS string, PCI-safe flag\n`record?` -- payment transaction record\n`gdsString?` -- GDS FOP string","status":"Implemented","purpose":"PCI-safe payment instruction builder and transaction recorder. Validates forms of payment, builds GDS FOP strings, records transactions. Never handles raw card numbers.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.8":{"id":"3.8","summary":"Retrieves an existing PNR/booking by record locator across distribution adapters. Read-only -- no side effects","className":"PnrRetrieval","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"4.1":{"id":"4.1","summary":"ETR generation with conjunction ticket support, BSP reporting, and commission handling","className":"TicketIssuance","input":"`record_locator` -- 6-char PNR\n`issuing_carrier` -- 2-letter IATA code\n`passenger_name` -- LAST/FIRST format\n`segments` -- flight segments with carrier, flight number, class, fare basis, dates, baggage\n`base_fare`, `base_fare_currency` -- fare amount\n`equivalent_fare?`, `equivalent_fare_currency?` -- currency conversion\n`taxes` -- tax breakdown items\n`fare_calculation` -- fare calculation line\n`form_of_payment` -- CASH, CREDIT_CARD, INVOICE, MISCELLANEOUS\n`endorsements?`, `commission?`, `bsp_reporting?`, `original_issue?`","output":"`tickets` -- `TicketRecord[]` (13-digit number, coupons with status, fare/tax breakdown, FOP, commission, BSP fields)\n`total_coupons` -- total across all tickets\n`is_conjunction` -- whether conjunction tickets were generated","status":"Implemented","purpose":"ETR (Electronic Ticket Record) generation with conjunction ticket support (auto-split for >4 coupons), BSP reporting fields, and commission handling.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"4.2":{"id":"4.2","summary":"EMD-A (associated) and EMD-S (standalone) issuance, RFIC/RFISC handling, coupon lifecycle","className":"EmdManagement","input":"`emd_type` -- `'EMD-A' | 'EMD-S'`\n`record_locator`, `issuing_carrier`, `passenger_name`\n`services` -- array of services with RFIC code (A-G), RFISC, description, amount, associated ticket/coupon for EMD-A\n`related_ticket_number?` -- for EMD-A","output":"`emd` -- `EmdRecord` (13-digit EMD number, coupons, amounts)\n`coupon_count`","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"4.3":{"id":"4.3","summary":"Ticket/EMD void processing -- coupon status check, carrier void window, BSP/ARC cut-off validation","className":"VoidAgent","input":"`document_number` -- 13-digit ticket/EMD number\n`issuing_carrier` -- 2-letter IATA code\n`coupons` -- coupon numbers and current statuses\n`issue_datetime` -- ISO datetime of issuance\n`current_datetime?` -- ISO datetime for void window check\n`settlement_system?` -- `'BSP' | 'ARC'`\n`bsp_cutoff_time?` -- HH:MM format","output":"`result` -- void permitted flag, rejection reason, message, void window hours, hours remaining, updated coupon statuses","status":"Implemented","purpose":"Ticket/EMD void processing with coupon status validation, carrier-specific void window enforcement, and BSP/ARC cut-off time checking.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"4.4":{"id":"4.4","summary":"Multi-channel itinerary rendering: Email (HTML+plain), SMS, WhatsApp. Carrier-neutral templates","className":"ItineraryDelivery","input":"`record_locator` -- booking reference\n`passengers` -- name, ticket number, frequent flyer\n`flights` -- flight details (number, origin, destination, times, cabin, seat, aircraft)\n`total_fare?`, `fare_currency?`\n`contact` -- email, phone, WhatsApp number\n`channels` -- `('EMAIL' | 'SMS' | 'WHATSAPP')[]`\n`agency_name?` -- for itinerary header","output":"`rendered` -- per-channel content (HTML/plain text, subject, SMS segment count)\n`channels_rendered` -- successfully rendered channels","status":"Implemented","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"4.5":{"id":"4.5","summary":"APIS validation, passport validity, visa check (stub for Agent 0.7)","className":"DocumentVerification","input":"`passengers` -- ticket name, passport name, passport number/expiry/nationality, DOB, gender\n`segments` -- destination country and travel date\n`passport_validity_months?` -- minimum validity beyond travel date (default: 6)\n`validation_date?` -- ISO date override","output":"`results` -- per-passenger verification (pass/fail, individual checks with severity)\n`all_passed` -- overall pass/fail\n`blocking_failures`, `advisory_warnings` -- counts","status":"Implemented","purpose":"APIS validation, passport validity checking (configurable months threshold), and name matching between ticket and passport.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"5.1":{"id":"5.1","summary":"ATPCO Category 31 voluntary change assessment: change fees, fare difference, residual value, waiver codes","className":"ChangeManagement","input":"`original_ticket` -- ticket number, issuing carrier, passenger name, record locator, issue date, base fare, total tax, fare basis, refundable flag, booking date, `original_departure_date?` (for DOT 7-day check)\n`requested_itinerary` -- new segments (carrier, flight, origin, destination, date, class, fare basis), new fare, new taxes\n`waiver_code?` -- airline-provided waiver identity (not skip-penalty by itself)\n`waiver_effect?` -- required when `waiver_code` set: `ELIMINATE_PENALTY | REDUCE_PENALTY | CHANGE_REFUND_FORM | CHANGE_REBOOKING_CLASS | IRROP_INVOLUNTARY` (see `docs/knowledge-base/waiver-typology.md`)\n`waiver_penalty_reduction?` -- required for `REDUCE_PENALTY`\n`permitted_booking_classes?` / `permitted_fare_basis_patterns?` -- required for `CHANGE_REBOOKING_CLASS`\n`current_datetime?` -- ISO datetime\n`cat31_rules?` -- filed Cat 31 rules (omit → ATPCO default no charge)\n`us_dot_24h?` -- `part_259_applicable?`, `booking_channel?` (`airline_direct` | `agency` | `ndc` | `gds` | `unknown`)\n`ticket_usage?` -- `FULLY_UNUSED` (default) or `PARTIALLY_USED`\n`residual_valuation?` -- required when `PARTIALLY_USED`: `PUBLISHED_FARE` or `CARRIER_SPECIFIC` unused amounts (issue #150; never coupon-ratio / MPA-P / haversine)","output":"`assessment` -- action (`REISSUE | REBOOK | REJECT`), change fee, fare difference, additional collection, residual value + `residual_method`, forfeited amount, tax difference, total due, Cat 31 `is_free_change` flag, summary\n`us_dot_24h` -- carrier remedy (`cancel` | `hold` | `unknown`), eligibility, ineligibility reasons (including `departure_within_7_days`, `channel_coverage_unknown`), entitlement (`penalty_free_cancel` | `unpaid_fare_hold` | `none` | `unknown`). **Not** a free-change boolean. Channel coverage follows carrier disclosure — not a baked-in “third-party never qualifies” rule.","status":"Implemented","purpose":"ATPCO Category 31 voluntary change assessment: change fees, fare difference, residual value, waiver codes, Cat 31 free-change window detection, and US DOT 14 CFR §259.5(b)(4) 24-hour reservation assessment (hold **or** cancel — carrier chooses; ≥7 days before departure). See `docs/knowledge-base/us-dot-24-hour-reservation.md`.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"5.2":{"id":"5.2","summary":"Ticket reissue with residual value, per-tax TFC carryforward (CARRY\\","className":"ExchangeReissue","input":"`original_ticket_number`, `conjunction_originals?`, `original_issue_date`\n`issuing_carrier`, `passenger_name`, `record_locator`\n`original_base_fare`, `original_taxes` -- from original ticket\n`change_fee`, `residual_value`, `residual_method` -- from Agent 5.1 (`FULLY_UNUSED` | `PUBLISHED_FARE` | `CARRIER_SPECIFIC`; never original − change fee)\n`new_segments` -- new flight segments\n`new_fare`, `new_fare_currency`, `new_taxes`, `fare_calculation`\n`form_of_payment` -- for additional collection\n`gds?` -- GDS for command generation\n`tax_carryforward_context` -- geography (`SAME_AIRPORT | SAME_CITY | DIFFERENT`), validity window flag, flown status, POS unchanged\n`tax_carryforward_rules` -- per-code rules covering every tax on original ∪ new (nature, min geography, YQ/YR flags, validity expiry action)\n`same_origin_destination?` -- **deprecated / ignored** for tax decisions (migration warning only)","output":"`reissue` -- new ticket record with full audit trail, exchange commands, `tax_decisions` on the audit trail\n`additional_collection` -- amount due\n`credit_amount` -- amount refundable if downgrade\n`tax_decisions` -- `{ tax_code, action: CARRY | RECALCULATE | FORFEIT, reason }[]`","status":"Implemented","purpose":"Ticket reissue with residual value application, **per-tax** carryforward (`CARRY | RECALCULATE | FORFEIT`), conjunction ticket handling, GDS exchange command generation, and full audit trail.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"5.3":{"id":"5.3","summary":"Carrier-initiated schedule change handling: trigger assessment, airline protection logic, regulatory entitlements (EU261, US DOT)","className":"InvoluntaryRebook","input":"`original_pnr` -- record locator, passenger, affected segment, issuing carrier, countries, checked-in flag, EU/Community carrier flag, optional endorsement\n`schedule_change` -- change type (incl. MISCONNECT), times, routing/equipment, misconnect shortfall\n`available_flights?` -- protection candidates with operating/marketing/alliance/interline + `endorsement_allows`\n`thresholds?` -- carrier-specific `time_change_minutes`, `measurement_point` (DEPARTURE|ARRIVAL), `misconnect_minutes` — required for those triggers\n`is_passenger_no_show?` -- no-show flag\n`is_oversale_denied_boarding?` -- only true for 14 CFR §250 oversales\n`eu261_inputs?` -- great-circle `distance_km` (Art.7(4)), delay/notice/rerouting/extraordinary, third-country benefits caveat","output":"`result` -- involuntary flag, trigger, ranked protection candidates (not executed), `art8_passenger_choice_required` + `art8_choices`, measurement point, regulatory flags (EU261/US DOT), original routing credit flag, summary","status":"Implemented","purpose":"Carrier-initiated schedule change / IRROP handling. Domain KB: `docs/knowledge-base/involuntary-rebook-irrop.md` (Regulation (EC) No 261/2004 — [CELEX:32004R0261](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32004R0261)).\n\n- **Triggers:** time change, routing change, equipment downgrade, cancellation, misconnect — with explicit dep vs arr measurement. **No hardcoded 60-minute threshold**; fail closed when carrier threshold input is missing.\n- **Reprotection candidates:** same operating → marketing → alliance → interline → other, with endorsement fail-closed. Alliance ≠ any alliance flight. **Do not silently \"same carrier first\"** — when EU261 applies, Art.8 passenger choice (refund vs re-route) is required before execution.\n- **EU261:** Art.3(1) matrix (EU depart any carrier / EU arrive Community carrier only). Art.7 compensation via great-circle bands only (never TPM). Art.8 choice surfaced on output.\n- **US DOT:** 14 CFR §250 IDB is oversale-specific — delays/cancels report `applies: false`.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"5.4":{"id":"5.4","summary":"Placeholder -- not yet implemented. Requires domain input on disruption priority rules","className":"DisruptionResponseAgent","status":"Coming Soon (stub)","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"5.5":{"id":"5.5","summary":"Placeholder -- not yet implemented. Requires domain input on change fee structures","className":"SelfServiceRebookingAgent","status":"Implemented","purpose":"Orchestrates Availability Search (1.1) and Change Management (5.1) to present priced rebooking alternatives (changeFee + fareDifference + taxDifference per option). Read-only -- does NOT execute the reissue; that is Exchange/Reissue (5.2). Involuntary reasons (schedule change / missed connection / cancellation) waive the change fee; voluntary changes honor ATPCO Cat 31 via 5.1.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"5.6":{"id":"5.6","summary":"Placeholder -- not yet implemented. Requires domain input on waitlist priority scoring","className":"WaitlistManagementAgent","status":"Implemented","purpose":"Stateful in-memory passenger waitlist queue with four operations: addEntry (priority computed at add time), clear (given N seats opened, remove top-N by priority), queryStatus (1-based position + estimated clearance probability), and expire (prune entries past their cutoff). State is in-memory only -- production deployments should pair it with a durable persistence layer.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"6.1":{"id":"6.1","summary":"ATPCO Category 33 refund processing: penalty application, commission recall, BSP/ARC reporting, conjunction ticket handling","className":"RefundProcessing","input":"`ticket_number`, `conjunction_tickets?`\n`issuing_carrier`, `passenger_name`, `record_locator`\n`base_fare`, `base_fare_currency`, `taxes`, `commission?`\n`refund_type` -- `'FULL' | 'PARTIAL' | 'TAX_ONLY'`\n`coupons_to_refund?` -- specific coupons (for partial)\n`partial_valuation?` -- required for `PARTIAL`: `PUBLISHED_FARE` or `CARRIER_SPECIFIC` unused base/taxes (issue #150; never coupon-ratio / MPA-P)\n`total_coupons`, `waiver_code?`, `waiver_effect?` (required with code), `fare_basis`, `is_refundable`\n`waiver_penalty_reduction?`, `waiver_refund_form?` -- companions per typology in `docs/knowledge-base/waiver-typology.md`\n`settlement_system` -- `'BSP' | 'ARC'`","output":"`refund` -- penalty applied, base fare refund, tax refund, tax breakdown, commission recalled, net refund, BSP/ARC reporting fields, audit trail\n`net_refund_amount`, `commission_recalled`","status":"Implemented","purpose":"ATPCO Category 33 refund processing: penalty application, commission recall, BSP/ARC reporting fields, conjunction ticket handling. Supports full, partial, and tax-only refunds.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.2":{"id":"6.2","summary":"Pre-ticketing audit: 10 checks covering fare integrity, passive/UC/churn (history-required), married integrity, TTL, and compliance to prevent Agency Debit Memos","className":"ADMPrevention","input":"`booking` -- record locator, passenger name, segments (with status, class, married group), base fare\n`fare_basis`, `booked_class`\n`commission_rate?`, `carrier_contracted_rate?` -- both caller-supplied; no embedded carrier tables\n`endorsement?`, `tour_code?`\n`is_net_remit?`, `net_contracted_amount?`\n`ttl_deadline?`, `ttl_timezone?`, `ttl_source?`, `current_datetime?`\n`duplicate_check_pnrs?`\n`segment_history?` -- required for churning; current status alone is insufficient\n`gds?` -- `SABRE` | `AMADEUS` | `TRAVELPORT` | `UNKNOWN` (Travelport DX marriage break)\n`churn_cycle_threshold?`, `churn_window_hours?`","output":"`result` -- all check results, overall pass/fail, blocking/warning counts","status":"Implemented","purpose":"Pre-ticketing audit with 10 checks: duplicate booking, fare/class mismatch, passive/unable/risky status (core HX/UC/UN/NO/TK + **per-host** maps — HN/PK/GK/YK are not universalized), churning (history-required), married segment integrity, TTL expiry (timezone / deadline-day), commission rate (caller-supplied only), endorsement box, tour code format, net remit validation.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.3":{"id":"6.3","summary":"Agency Debit Memo receipt, assessment, dispute, and Agency Credit Memo application workflows","className":"ADMACMProcessingAgent","input":"`operation` -- `'receiveADM' | 'receiveACM' | 'assessADM' | 'disputeADM' | 'acceptADM' | 'escalateADM' | 'applyACM' | 'getADM' | 'getPendingWithDeadlines'`\nOperation-specific fields: ticket number, airline, amount, reason code, dispute ground/evidence, ADM/ACM IDs","output":"`adm?` -- ADM record with status history\n`acm?` -- ACM record\n`assessment?` -- days remaining, window expired, recommended action\n`disputeResult?` -- dispute outcome\n`pendingDeadlines?` -- urgent ADMs approaching deadline","status":"Implemented","purpose":"Agency Debit Memo receipt, assessment, dispute, and Agency Credit Memo application workflows. Tracks dispute deadlines (15-day window), supports dispute grounds, and manages status transitions.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.4":{"id":"6.4","summary":"Multi-channel customer notification generation for flight disruptions, refunds, and operational changes. 8 notification types x 4 channels","className":"CustomerCommunication","input":"`operation` -- `'generateNotification' | 'generateBatch' | 'getTemplate'`\n`notificationType?` -- notification type\n`channel?` -- delivery channel\n`variables?` -- template variables (passenger name, flight info, amounts, etc.)\n`batchRequests?` -- for batch generation","output":"`notification?` -- generated notification with body, subject, SMS segments, used/missing variables\n`notifications?` -- batch results\n`template?` -- template info with required variables","status":"Implemented","purpose":"Multi-channel customer notification generation. 8 notification types (flight cancelled, delayed, gate change, rebooking confirmed, refund processed, schedule change, waitlist cleared, ADM received) x 4 channels (Email HTML, Email text, SMS, WhatsApp).","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.5":{"id":"6.5","summary":"Complaint submission, EU261/US DOT compensation calculation, case management, and regulatory DOT record generation","className":"FeedbackComplaintAgent","input":"`operation` -- `'submitComplaint' | 'updateStatus' | 'getCase' | 'listCases' | 'calculateCompensation' | 'generateDOTRecord'`\nComplaint fields: type, passenger, booking reference, airline, flight, description\nCompensation fields: regulation, distance, delay, alternative offered, fare paid, cabin class\nCase management: case ID, status transitions","output":"`complaintCase?` -- full case record with status history, compensation result\n`cases?` -- filtered case list\n`compensation?` -- EU261/US DOT calculation (eligibility, base/final amount, reduction, notes)\n`dotRecord?` -- DOT regulatory record","status":"Implemented","purpose":"Complaint submission, EU261/US DOT compensation calculation, case management with status tracking, and DOT regulatory record generation.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.6":{"id":"6.6","summary":"Mileage accrual calculation, redemption eligibility, status benefits, and alliance status matching","className":"LoyaltyMileageAgent","input":"`operation` -- `'calculateAccrual' | 'checkRedemptionEligibility' | 'getStatusBenefits' | 'matchStatus'`\nAccrual: operating/crediting carrier, booking class, distance, loyalty status\nRedemption: distance, cabin, partner flag, current balance\nBenefits: airline, status tier\nMatch: source/target airline, source status","output":"`accrual?` -- base miles, bonus miles, total, earn rate, partner flag\n`redemption?` -- eligibility, miles required, remaining balance\n`statusBenefits?` -- benefit list by tier\n`statusMatch?` -- matched status at target airline","status":"Implemented","purpose":"Mileage accrual calculation, redemption eligibility checking, status benefits lookup, and cross-airline status matching.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.1":{"id":"7.1","summary":"Matches agency booking records against BSP HOT files, validates commission, identifies discrepancies, flags issues before remittance deadline","className":"BSPReconciliation","input":"`hot_records` -- BSP HOT file records (ticket number, passenger, origin/destination, airline, amounts, commission, transaction type / DISH TRNC, **transaction currency CUTP**, optional reporting currency, billing period, ORIT / RTDN / conjunction set)\n`agency_records` -- agency-side booking records for comparison (optional `original_ticket_number`, `related_ticket_number`, `conjunction_ticket_numbers`)","output":"Discrepancies with severity and type (includes `UNMATCHED_EXCHANGE`, `CONJUNCTION_SET_MISMATCH`)\nSummary with `currencies_present` (multi-currency HOT awareness)\nCommission / amount compares only when agency and HOT transaction currencies match (no silent IROE/ICER FX)","status":"Implemented","purpose":"Matches agency booking records against BSP HOT files (DISH Rev 23), validates commission rates, identifies discrepancies (missing records, duplicates, amount/commission/currency mismatches, unmatched ADM/ACM, exchange/conjunction cross-refs), and flags issues before remittance deadline.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.2":{"id":"7.2","summary":"Processes ARC IAR weekly billing, validates commission rates against airline contracts, flags pricing/commission errors","className":"ARCReconciliation","input":"`iar_records` -- ARC IAR records (document number, amounts, commission, transaction type, settlement week, ADM issue dates)\n`agency_records` -- agency-side records for comparison","output":"Matched/unmatched records, discrepancies with severity, ADM dispute window warnings","status":"Implemented","purpose":"Processes ARC IAR (Interactive Agent Reporting) weekly billing, validates commission rates against airline contracts, flags pricing/commission errors, and manages ADM/ACM disputes within the 15-day window.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.3":{"id":"7.3","summary":"Commission agreement management, rate validation, incentive calculation","className":"CommissionManagementAgent","input":"`operation` -- `'registerAgreement' | 'getRate' | 'validateCommission' | 'calculateIncentive' | 'listAgreements'`\nAgreement data: agent ID, airline, type, rate, basis (percent/flat per ticket/segment), fare basis patterns, validity dates, minimum tickets\nValidation: claimed rate vs expected rate\nIncentive: period, ticket count, total fare","output":"`agreement?` -- registered agreement\n`rate?` -- applicable commission rate\n`validation?` -- match/overstated/understated status with variance\n`incentive?` -- earned incentive amount, threshold met flag","status":"Implemented","purpose":"Commission agreement management: register agreements (override, incentive, backend, net fare, standard), look up rates by airline/fare basis, validate claimed commission, and calculate incentive earnings.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.4":{"id":"7.4","summary":"Placeholder -- not yet implemented. Requires domain input on interline prorate methodology","className":"InterlineSettlementAgent","status":"Coming Soon (stub)","purpose":"Requires domain input on interline prorate methodology and SIS (Simplified Interline Settlement) billing rules before implementation can proceed.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"7.5":{"id":"7.5","summary":"Aggregates transaction data into reports (revenue by route, margin analysis, unused tickets, etc.)","className":"FinancialReportingAgent","input":"`type` -- report type (9 report types available)\n`period` -- date range\n`filters?` -- airlines, agents, corporate IDs, currencies, minimum amount\n`groupBy?` -- grouping dimensions\n`records` -- financial records (ticket, refund, ADM, ACM, commission, fee)\n`currency?` -- reporting currency","output":"Report line items with revenue, cost, commission, net per group\nReport totals","status":"Implemented","purpose":"Generates financial reports: revenue by route/agent/corporate client, margin analysis, cost tracking, commission summary, spend by supplier, unused ticket value, and settlement summary.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.6":{"id":"7.6","summary":"Coupon lift recording, revenue recognition, uplift/deferred revenue reporting","className":"RevenueAccountingAgent","input":"`operation` -- `'recordLift' | 'recognizeRevenue' | 'getUpliftReport' | 'getDeferredRevenue' | 'recordVoid' | 'recordRefund'`\nLift data: ticket number, coupon number, flight details, fare amount\nReport parameters: date range","output":"Lift records, revenue recognition results, uplift reports (by route/cabin with average yield), deferred revenue reports","status":"Implemented","purpose":"Coupon lift tracking and revenue recognition: record lifted coupons, recognize revenue per flight, generate uplift reports (by route, by cabin), track deferred revenue from open coupons, and handle voids/refunds.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.1":{"id":"8.1","summary":"Stores/retrieves traveler preferences, documents, loyalty programs. Applies profiles to PNRs via SSR injection","className":"TravelerProfileAgent","input":"`operation` -- `'get' | 'create' | 'update' | 'apply_to_pnr' | 'search'`\nProfile data: name, DOB, nationality, passport, loyalty numbers, seat/meal preference, contact info, corporate/employee ID, department, cost center\nPNR application: GDS system, segments for APIS generation","output":"`profile?` -- traveler profile record\n`profiles?` -- search results\nPNR application: generated SSR/OSI commands","status":"Implemented","purpose":"Traveler preferences, identity documents, loyalty programs, and PNR prefill. CRUD operations plus apply-to-PNR for generating SSR/APIS commands.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.2":{"id":"8.2","summary":"Corporate travel policy enforcement, negotiated fares, booking validation","className":"CorporateAccountAgent","input":"`operation` -- `'get_account' | 'create_account' | 'update_account' | 'validate_booking' | 'get_policy' | 'list_accounts' | 'get_preferred_suppliers'`\nAccount data: company name, IATA number, travel policy, negotiated fares, contact info\nBooking validation: segments, cabin, fare amount, advance days","output":"`account?` -- corporate account record\n`accounts?` -- account list\n`validation?` -- policy violations (hard/soft) with details\n`policy?` -- travel policy rules\n`suppliers?` -- preferred suppliers","status":"Implemented","purpose":"Corporate travel policy management, negotiated fare lookup, and booking validation against policy rules (cabin limits, fare ceilings, advance booking, preferred/blacklisted airlines).","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.3":{"id":"8.3","summary":"PNR quality checks, ticketing deadline monitoring, duplicate/passive detection","className":"MidOfficeAgent","input":"`trigger` -- `'scheduled_sweep' | 'pnr_created' | 'ticket_deadline_approaching' | 'queue_pending' | 'manual_review_request'`\n`pnrs` -- PNR records with segments, deadlines, APIS/contact/FOP flags\n`current_datetime?` -- ISO timestamp (compared as Zulu)","output":"Per-PNR issues with severity (urgent/high/medium/low) and issue codes\nSummary counts","status":"Implemented","purpose":"PNR quality checks and ticketing deadline monitoring. Scans PNRs for 10 issue types: TTL urgent/approaching, missing segment status, missing APIS, missing contact/FOP, duplicate PNR, passive segment, policy violation, married segment incomplete.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.4":{"id":"8.4","summary":"Aggregates transaction data into reports (booking volume, revenue, top routes, policy compliance)","className":"ReportingAgent","input":"`report_type` -- report type\n`date_from`, `date_to` -- date range\n`filters?` -- corporate ID, agent, airline, department, currency\n`transactions` -- transaction records (ticket, amounts, airline, dates, in-policy flag, used flag)","output":"Report rows grouped by the relevant dimension\nSummary totals","status":"Implemented","purpose":"Transaction aggregation and report generation across 9 report types: booking volume, revenue summary, top routes, agent productivity, policy compliance, spend by traveler/department/supplier, unused tickets.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.5":{"id":"8.5","summary":"Locates travelers in active itineraries during disruptions with destination risk assessment","className":"DutyCareAgent","input":"`operation` -- `'locate_travelers' | 'get_traveler_itinerary' | 'assess_destination_risk' | 'mark_accounted_for'`\nItineraries: traveler ID, segments with dates/times/status\nRisk: country code\nAccountability: traveler ID","output":"`locatedTravelers?` -- current location, status (IN_TRANSIT/AT_DESTINATION/DEPARTED/UNKNOWN), accounted-for flag\n`itinerary?` -- full traveler itinerary\n`risk?` -- country risk level (low/medium/high/critical) with notes","status":"Implemented","purpose":"Traveler location tracking, destination risk assessment, and accountability management for corporate duty-of-care obligations.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.1":{"id":"9.1","summary":"Coordinates multi-agent workflows as a single callable pipeline (search_to_price, book_to_ticket, full_booking, etc.)","className":"OrchestratorAgent","input":"`workflow` -- workflow name\n`input` -- workflow input data\n`options?` -- `stop_on_error?`, `timeout_ms?`","output":"`workflow` -- workflow name\n`status` -- `'completed' | 'failed' | 'partial'`\n`steps` -- per-step results (agent ID, status, duration, output/error)\n`total_duration_ms`\n`final_output?` -- last step output","usage":"Accepts injectable `StepExecutor` for testing without real agent imports. Then call initialize() and execute({ data }).","status":"Implemented","purpose":"Multi-agent workflow coordination. Defines named workflows (search-to-price, book-to-ticket, full booking, exchange flow, refund flow) as step sequences. Supports conditional steps, parallel execution, error handling (stop/skip/continue), and pipeline building."},"9.2":{"id":"9.2","summary":"RAG over travel knowledge base with BM25 relevance scoring and optional hybrid scoring via injectable EmbeddingProvider","className":"KnowledgeAgent","input":"`operation` -- `'query' | 'index_document' | 'list_topics' | 'get_document'`\nQuery: query string, topic filter, max results\nIndex: document ID, title, content, tags, topic","output":"`results?` -- ranked results with relevance score, excerpt, full content\n`document?` -- specific document\n`topics?` -- available topic list\n`query_time_ms?`","status":"Implemented","purpose":"RAG (Retrieval-Augmented Generation) over the travel knowledge base. Indexes documents by topic, supports BM25 + vector hybrid search with injectable embedding provider.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.3":{"id":"9.3","summary":"Tracks agent health, API latency, error rates, SLA compliance","className":"MonitoringAgent","input":"`operation` -- `'record_metric' | 'get_health' | 'list_alerts' | 'acknowledge_alert' | 'get_sla_report'`\nMetric: agent ID, metric type (latency_ms/error/success/timeout), value\nAlert: alert ID for acknowledgment","output":"`health?` -- agent health (status, p50/p95 latency, error rate, total calls)\n`alerts?` -- alert list with severity and fired timestamp\n`slaReport?` -- availability percent, p95 latency, error count","status":"Implemented","purpose":"Agent health monitoring: latency tracking (p50/p95), error rates, SLA compliance reporting. Records metrics, fires alerts on threshold violations, supports alert acknowledgment.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.4":{"id":"9.4","summary":"Audit trail, PII redaction, GDPR/PCI/IATA compliance","className":"AuditAgent","input":"`operation` -- `'log_event' | 'query_audit_log' | 'flag_compliance_issue' | 'get_compliance_report' | 'redact_pii'`\nEvent: type (agent_decision, data_access, booking_created, etc.), agent ID, user/session ID, payload\nCompliance: issue type, description, severity, affected records","output":"`entry?` -- audit log entry with hash, PII redaction flag, retention days\n`entries?` -- query results\n`issue?` -- flagged compliance issue\n`report?` -- compliance report (events with PII, redaction counts, open issues by severity)\n`redactedPayload?` -- PII-redacted data","status":"Implemented","purpose":"Audit trail logging with SHA-256 payload hashing, PII redaction (credit cards, passports, emails, phone numbers, DOB), GDPR/PCI/IATA compliance issue flagging, and compliance reporting.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.5":{"id":"9.5","summary":"Manages third-party agent extensions and capability discovery","className":"PluginManagerAgent","input":"`operation` -- `'register_plugin' | 'unregister_plugin' | 'list_plugins' | 'get_plugin' | 'discover_capabilities' | 'enable_plugin' | 'disable_plugin'`\nPlugin data: name, version, description, author, capabilities, agent IDs, metadata","output":"`plugin?` -- plugin record\n`plugins?` -- plugin list\n`capabilities?` -- capability-to-plugin mapping\n`message?` -- operation result message","status":"Implemented","purpose":"Third-party agent extension management: register/unregister plugins, enable/disable, capability discovery, and plugin metadata management.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.6":{"id":"9.6","summary":"Aggregates agent execution metrics from the EventStore within a given time window. Identifies degraded agents","className":"PerformanceAuditAgent","status":"Implemented","purpose":"Aggregates agent execution metrics from the EventStore within a given time window and identifies degraded agents. Read-only -- no side effects.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"9.7":{"id":"9.7","summary":"Analyses routing decisions and outcomes from the EventStore within a given time window","className":"RoutingAuditAgent","status":"Implemented","purpose":"Analyses routing decisions and outcomes from the EventStore within a given time window. Read-only -- no side effects.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"9.8":{"id":"9.8","summary":"Accepts performance and routing audit reports and produces deterministic recommendations","className":"RecommendationAgent","status":"Implemented","purpose":"Accepts performance and routing audit reports and produces deterministic recommendations. Read-only -- no side effects.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"9.9":{"id":"9.9","summary":"Queries EventStore events, computes metrics against configurable thresholds, and produces alerts","className":"AlertAgent","status":"Implemented","purpose":"Queries EventStore events, computes metrics against configurable thresholds, and produces alerts. Read-only -- no side effects.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"20.1":{"id":"20.1","summary":"Multi-source hotel availability search across GDS hotel segments, direct APIs, and channel manager feeds","className":"HotelSearchAggregatorAgent","input":"`destination` -- city name, airport code, or coordinates\n`checkIn` -- ISO date string (YYYY-MM-DD)\n`checkOut` -- ISO date string (YYYY-MM-DD)\n`rooms` -- number of rooms needed\n`adults` -- number of adult guests per room\n`children?` -- number of child guests per room\n`starRating?` -- minimum star rating filter\n`maxRatePerNight?` -- maximum nightly rate filter (decimal string)\n`currency?` -- ISO 4217 currency for rate filtering/display\n`rateType?` -- rate type filter\n`chainPreference?` -- chain code (e.g., `\"MC\"` for Marriott)\n`timeoutMs?` -- per-adapter timeout in milliseconds (default: 5000)\n`adapterIds?` -- specific adapter IDs to query (all if omitted)","output":"`properties` -- raw hotel results from all sources (NOT deduplicated)\n`totalResults` -- total result count across all adapters\n`adapterResults` -- per-adapter summary (ID, name, count, response time, timeout/error)\n`partialResults` -- true if some adapters timed out or errored\n`searchId` -- unique search ID for tracing","usage":"const agent = new HotelSearchAggregatorAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: {\n    destination: 'New York',\n    checkIn: '2026-06-01',\n    checkOut: '2026-06-03',\n    rooms: 1,\n    adults: 2,\n  },\n});\n// result.data.totalResults => 45\n// result.data.partialResults => false","status":"Implemented","purpose":"Multi-source hotel availability search across GDS hotel segments, direct APIs (Amadeus Hotel, Hotelbeds, Duffel Stays), and channel manager feeds. Returns raw, unmerged results from all connected sources. Supports injectable `HotelSourceAdapter` for plugging in custom sources."},"20.2":{"id":"20.2","summary":"Identifies duplicate properties from multi-source results and merges them into canonical records","className":"PropertyDeduplicationAgent","input":"`properties` -- raw hotel results from Agent 20.1\n`thresholds?` -- custom merge thresholds\n`autoMerge` -- score above which properties are auto-merged (default: 0.85)\n`review` -- score above which properties are flagged for review (default: 0.65)","output":"`canonical` -- canonical property records (one per physical property)\n`mergeLog` -- full audit trail of merge/separate decisions (property IDs, score, decision type, score breakdown)\n`stats` -- summary (input count, output count, auto-merged, review-flagged, separated)","usage":"const agent = new PropertyDeduplicationAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: { properties: rawResults },\n});\n// result.data.stats.inputCount => 45\n// result.data.stats.outputCount => 28\n// result.data.stats.autoMerged => 12","status":"Implemented","purpose":"Takes raw multi-source hotel results from Agent 20.1 and identifies duplicate properties (40-60% of multi-source results are duplicates). Merges them into canonical property records using weighted scoring: Jaro-Winkler name similarity (0.3), normalized address Levenshtein (0.2), Haversine coordinate proximity (0.25), chain code match (0.15), and star rating match (0.1)."},"20.3":{"id":"20.3","summary":"Standardizes hotel content (room types, amenity names, descriptions, photos) into a consistent OTAIP taxonomy","className":"ContentNormalizationAgent","input":"`properties` -- canonical property records from Agent 20.2","output":"`properties` -- normalized property content records, each containing:\n`canonicalId` -- pass-through from 20.2\n`property` -- original canonical property\n`normalizedRoomTypes` -- room types mapped to OTAIP taxonomy\n`normalizedAmenities` -- amenities mapped to OTAIP taxonomy\n`scoredPhotos` -- scored and categorized photos (category, quality score, primary flag)\n`unmappedRoomTypes` -- raw room types that could not be normalized\n`unmappedAmenities` -- raw amenity strings that could not be normalized\n`stats` -- totals for properties, mapped/unmapped room types, mapped/unmapped amenities","usage":"const agent = new ContentNormalizationAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: { properties: canonicalProperties },\n});\n// result.data.stats.totalRoomTypesMapped => 84\n// result.data.stats.totalAmenitiesUnmapped => 3","status":"Implemented","purpose":"Standardizes hotel content (room types, amenity names, photos) into a consistent OTAIP taxonomy for comparison and display. Maps raw room types from each source to the normalized taxonomy, merges amenities via union merge, and scores/categorizes photos."},"20.4":{"id":"20.4","summary":"Compares rates for the same canonical property across all sources, identifies best available rate, detects rate parity violations","className":"RateComparisonAgent","input":"`properties` -- canonical properties with source results containing rates\n`currency?` -- preferred currency for display (default: USD)\n`nights?` -- number of nights for the stay (default: 1)","output":"`comparisons` -- per-property rate comparison, each containing:\n`canonicalId` -- canonical property ID\n`propertyName` -- property name\n`rates` -- all rates sorted by total cost (lowest first), with full cost breakdown (room charges, mandatory fees, taxes, grand total)\n`bestByRateType` -- best rate per rate type\n`parity` -- rate parity analysis (at parity flag, lowest/highest source, spread percentage)\n`totalProperties` -- total properties compared\n`parityViolations` -- count of properties with rate parity violations","usage":"const agent = new RateComparisonAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: { properties: canonicalProperties, nights: 2 },\n});\n// result.data.comparisons[0].rates[0].totalCost.grandTotal => { amount: '289.00', currency: 'USD' }\n// result.data.parityViolations => 3","status":"Implemented","purpose":"Compares rates for the same canonical property across all sources, identifies best available rate per rate type, and detects rate parity violations (>2% spread between lowest and highest source). Includes ALL mandatory fees (resort fees, destination fees, taxes) in total cost breakdown."},"20.5":{"id":"20.5","summary":"Executes hotel bookings with three-layer confirmation code system (CRS, PMS, Channel)","className":"HotelBookingAgent","input":"`operation` -- `'book' | 'verify_rate' | 'get_booking'`\n`bookingRequest?` -- required for `book`/`verify_rate`:\n`canonicalPropertyId` -- from Agent 20.2\n`rateId` -- from Agent 20.4\n`source` -- hotel source to book through\n`checkIn` / `checkOut` -- ISO date strings\n`rooms` -- number of rooms\n`guest` -- guest details (name, email, phone, loyalty info)\n`paymentModel` -- payment model\n`specialRequests?` -- free text\n`bookingId?` -- required for `get_booking`","output":"`success` -- whether the operation succeeded\n`booking?` -- booking record (ID, three-layer confirmation codes, status, total charged, payment model, virtual card info, cancellation policy/deadline, guest, original request)\n`error?` -- error message if failed\n`rateChanged?` -- whether rate changed between search and booking\n`newRate?` -- new rate if changed","usage":"const agent = new HotelBookingAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: {\n    operation: 'book',\n    bookingRequest: {\n      canonicalPropertyId: 'canon-001',\n      rateId: 'rate-001',\n      source: 'amadeus_hotel',\n      checkIn: '2026-06-01',\n      checkOut: '2026-06-03',\n      rooms: 1,\n      guest: { firstName: 'John', lastName: 'Smith', email: 'john@example.com' },\n      paymentModel: 'merchant',\n    },\n  },\n});\n// result.data.booking?.confirmation.crs => \"CRS-ABC123\"","status":"Implemented","purpose":"Executes hotel bookings through the optimal source. Manages the full booking flow from rate verification through confirmation, including three-layer confirmation codes (CRS, PMS, channel). Supports VCN (Virtual Card Number) payment with dual folio requirements."},"20.6":{"id":"20.6","summary":"Post-booking changes: free modifications, date changes (cancel/rebook), cancellations with penalty calculation, no-show processing","className":"HotelModificationAgent","input":"`operation` -- `'modify' | 'cancel' | 'check_penalty' | 'process_no_show'`\n`bookingId` -- existing booking ID\n`modifications?` -- free modifications (guest name, bed type, smoking preference, special requests, accessibility needs, guest count)\n`dateChange?` -- new check-in / check-out dates (triggers cancel/rebook)\n`bookedAt?` -- booking timestamp for California 24hr rule check\n`cancellationPolicy?` -- current cancellation policy\n`checkInDate?` -- for deadline calculations\n`nightlyRate?` -- nightly rate from booking record (penalty base)","output":"`success` -- whether the operation succeeded\n`classification` -- `'free_modification' | 'cancel_rebook_required' | 'not_modifiable'`\n`isFreeMod` -- whether this is a free modification\n`penalty?` -- penalty calculation (amount, type, deadline, free window flag, California rule flag)\n`rebookRequired` -- whether a rebook is needed (for date changes)\n`newBookingId?` -- updated confirmation codes (for successful modifications)\n`message` -- error or status message","usage":"const agent = new HotelModificationAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: {\n    operation: 'cancel',\n    bookingId: 'BK-001',\n    cancellationPolicy: { type: 'free_cancellation', deadline: '2026-05-30T00:00:00Z' },\n    checkInDate: '2026-06-01',\n    bookedAt: '2026-04-01T10:00:00Z',\n  },\n});\n// result.data.classification => \"free_modification\"\n// result.data.penalty?.isWithinFreeWindow => true","status":"Implemented","purpose":"Handles post-booking changes: free modifications (guest name, bed type, special requests), date changes (which require cancel/rebook -- NOT modifications), cancellations with penalty calculation, and no-show processing. Enforces California 24-hour cancellation rule where applicable."},"20.7":{"id":"20.7","summary":"Cross-checks CRS-to-PMS booking data to detect discrepancies before guest arrival","className":"ConfirmationVerificationAgent","input":"`operation` -- `'verify' | 'check_pms_sync' | 'batch_verify'`\n`bookingId` -- booking ID to verify\n`confirmation` -- three-layer confirmation codes from booking\n`crsData` -- CRS-side booking data (confirmation code, guest name, dates, room type, rates, status)\n`pmsData?` -- PMS-side booking data (may be missing if PMS hasn't synced yet)\n`guest` -- guest details for name verification\n`hoursUntilCheckin?` -- hours until check-in (for escalation urgency)\n`batchBookingIds?` -- additional booking IDs (for `batch_verify`)","output":"`verified` -- whether verification passed with no critical issues\n`discrepancies` -- all detected discrepancies (field, CRS value, PMS value, severity, message)\n`escalationRequired` -- whether human/agent escalation is needed\n`escalationReasons` -- why escalation is needed (pms_code_missing, rate_mismatch, date_mismatch, guest_name_mismatch, waitlist_status, tentative_status, room_type_mismatch, multiple_discrepancies)\n`verifiedAt` -- verification timestamp\n`message` -- summary message","usage":"const agent = new ConfirmationVerificationAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: {\n    operation: 'verify',\n    bookingId: 'BK-001',\n    confirmation: { crs: 'CRS-ABC', pms: 'PMS-123', channel: 'CH-456' },\n    crsData: {\n      confirmationCode: 'CRS-ABC',\n      guestName: 'SMITH/JOHN',\n      checkIn: '2026-06-01',\n      checkOut: '2026-06-03',\n      roomType: 'King Standard',\n      nightlyRate: { amount: '189.00', currency: 'USD' },\n      totalRate: { amount: '378.00', currency: 'USD' },\n      status: 'confirmed',\n    },\n    guest: { firstName: 'John', lastName: 'Smith' },\n  },\n});\n// result.data.verified => true\n// result.data.discrepancies.length => 0","status":"Implemented","purpose":"Cross-checks CRS and PMS booking data to detect discrepancies before guest arrival. Escalates missing PMS codes, waitlist/tentative status, rate/date mismatches. PMS sync can take 1-4 hours; delays beyond 24 hours trigger escalation."},"20.8":{"id":"20.8","summary":"Thin typed wrapper around Hotelbeds Activities search for route→fill orchestration and product-layer activity_search mapping.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"20.9":{"id":"20.9","summary":"Thin typed wrapper around Hotelbeds Transfers search for route→fill orchestration.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."}}}</script>
   <script>
     const payload = JSON.parse(document.getElementById('graph-data').textContent);
     const graph = payload.graph;
diff --git a/docs/agents/stage-5-exchange.md b/docs/agents/stage-5-exchange.md
index 2d37544..ca6bc63 100644
--- a/docs/agents/stage-5-exchange.md
+++ b/docs/agents/stage-5-exchange.md
@@ -24,9 +24,11 @@ ATPCO Category 31 voluntary change assessment: change fees, fare difference, res
 - `current_datetime?` -- ISO datetime
 - `cat31_rules?` -- filed Cat 31 rules (omit → ATPCO default no charge)
 - `us_dot_24h?` -- `part_259_applicable?`, `booking_channel?` (`airline_direct` | `agency` | `ndc` | `gds` | `unknown`)
+- `ticket_usage?` -- `FULLY_UNUSED` (default) or `PARTIALLY_USED`
+- `residual_valuation?` -- required when `PARTIALLY_USED`: `PUBLISHED_FARE` or `CARRIER_SPECIFIC` unused amounts (issue #150; never coupon-ratio / MPA-P / haversine)
 
 **Output (`ChangeManagementOutput`):**
-- `assessment` -- action (`REISSUE | REBOOK | REJECT`), change fee, fare difference, additional collection, residual value, forfeited amount, tax difference, total due, Cat 31 `is_free_change` flag, summary
+- `assessment` -- action (`REISSUE | REBOOK | REJECT`), change fee, fare difference, additional collection, residual value + `residual_method`, forfeited amount, tax difference, total due, Cat 31 `is_free_change` flag, summary
 - `us_dot_24h` -- carrier remedy (`cancel` | `hold` | `unknown`), eligibility, ineligibility reasons (including `departure_within_7_days`, `channel_coverage_unknown`), entitlement (`penalty_free_cancel` | `unpaid_fare_hold` | `none` | `unknown`). **Not** a free-change boolean. Channel coverage follows carrier disclosure — not a baked-in “third-party never qualifies” rule.
 
 ---
@@ -46,7 +48,7 @@ Ticket reissue with residual value application, **per-tax** carryforward (`CARRY
 - `original_ticket_number`, `conjunction_originals?`, `original_issue_date`
 - `issuing_carrier`, `passenger_name`, `record_locator`
 - `original_base_fare`, `original_taxes` -- from original ticket
-- `change_fee`, `residual_value`, `waiver_code?` -- from Agent 5.1
+- `change_fee`, `residual_value`, `residual_method` -- from Agent 5.1 (`FULLY_UNUSED` | `PUBLISHED_FARE` | `CARRIER_SPECIFIC`; never original − change fee)
 - `new_segments` -- new flight segments
 - `new_fare`, `new_fare_currency`, `new_taxes`, `fare_calculation`
 - `form_of_payment` -- for additional collection
diff --git a/docs/agents/stage-6-settlement.md b/docs/agents/stage-6-settlement.md
index 2f2b7cd..ad82527 100644
--- a/docs/agents/stage-6-settlement.md
+++ b/docs/agents/stage-6-settlement.md
@@ -21,6 +21,7 @@ ATPCO Category 33 refund processing: penalty application, commission recall, BSP
 - `base_fare`, `base_fare_currency`, `taxes`, `commission?`
 - `refund_type` -- `'FULL' | 'PARTIAL' | 'TAX_ONLY'`
 - `coupons_to_refund?` -- specific coupons (for partial)
+- `partial_valuation?` -- required for `PARTIAL`: `PUBLISHED_FARE` or `CARRIER_SPECIFIC` unused base/taxes (issue #150; never coupon-ratio / MPA-P)
 - `total_coupons`, `waiver_code?`, `waiver_effect?` (required with code), `fare_basis`, `is_refundable`
 - `waiver_penalty_reduction?`, `waiver_refund_form?` -- companions per typology in `docs/knowledge-base/waiver-typology.md`
 - `settlement_system` -- `'BSP' | 'ARC'`
diff --git a/docs/knowledge-base/partial-refund-residual-value.md b/docs/knowledge-base/partial-refund-residual-value.md
new file mode 100644
index 0000000..2b7b768
--- /dev/null
+++ b/docs/knowledge-base/partial-refund-residual-value.md
@@ -0,0 +1,206 @@
+# Partial refund / residual value — passenger path
+
+Source: GitHub issue #150 (TMC / revenue-accounting domain input). Authoritative for Agents **5.1**, **5.2**, and **6.1**. Anything missing here is an open `DOMAIN_QUESTION` — never invent.
+
+Related: Cat 31/33 no-match defaults and waiver typology — issue [#138](https://github.com/TelivityAI/otaip/issues/138) / PR [#153](https://github.com/TelivityAI/otaip/pull/153) (`docs/knowledge-base/waiver-typology.md` when merged).
+
+## Scope
+
+This document covers **passenger-facing** residual value and partial refunds on air tickets (voluntary change residual for reissue; Cat 33 voluntary refund of unused value after partial use).
+
+It does **not** cover airline-to-airline interline revenue allocation.
+
+## Authoritative sources (cite; do not invent)
+
+| Source | Role for passenger residual |
+| --- | --- |
+| **ATPCO Category 33** (public category definition) | Conditions and applicable charges for voluntary refunds. **No Cat 33 data, or no applicable provision matched → refund permitted at no charge** (ATPCO public default). Not fail-closed. Not a DOMAIN_QUESTION. |
+| **THB — IATA Ticketing Handbook** | Industry ticketing procedures for passenger documents / residual handling. **Cite by name only — never commit paid handbook text or extracts into this repository.** |
+| **MPA-P / Prorate Manual** | **Out of scope** for passenger residual — airline interline settlement only. |
+
+Public Cat 33 wording (ATPCO): Category 33 defines the conditions and applicable charges under which voluntary refunds are permitted. In the absence of voluntary refunds data or when no applicable provision is matched, a refund is permitted at no charge and with no restrictions for that fare.
+
+## Forbidden arithmetic (reject as a general rule)
+
+| Invented formula | Why it is wrong |
+| --- | --- |
+| `residual = original − change fee` | Change fee is a **separate** Cat 31/16 collection. Residual is unused **ticketed fare value**, not fare-minus-penalty. |
+| `partial refund = original − "used portion"` without a method | "Used portion" is undefined until an explicit valuation method prices the flown sectors. |
+| Coupon-count ratio (`base × refundable_coupons / total_coupons`) | Equal coupon split invents value; through fares are not linear in coupon count. |
+| Haversine / great-circle split of a through fare | Distance approximation is not a published fare and is not a filed residual method. |
+| MPA-P / TPM / PFM tables applied to the passenger | **MPA-P is airline interline settlement**, not passenger residual. |
+
+## What passenger residual actually is
+
+**Passenger refund / residual is governed by ATPCO Category 33 conditions/charges, applied with ticketing practice from the IATA Ticketing Handbook (THB).**
+
+That means:
+
+1. **Penalty / eligibility** — from Cat 33 (filed provision, or ATPCO **no-match free** default).
+2. **Unused fare value on partial use** — from an **explicit** valuation method supplied by the caller (`PUBLISHED_FARE` for flown sectors, or `CARRIER_SPECIFIC`). Engines do not invent flown amounts, MPA-P splits, or handbook extracts.
+
+**THB is the IATA Ticketing Handbook.** Cite it by name only. Do not invent alternate expansions of the acronym, and do not commit paid handbook text.
+
+## Fail-closed vs free — same split as #153 / waiver typology
+
+| Situation | Correct engine behavior |
+| --- | --- |
+| No Cat 33 data, or no provision matches | ATPCO public default: **free** refund (no Cat 33 charge). **Not** fail-closed. **Not** a DOMAIN_QUESTION. |
+| Filed Cat 33 provision matches | Apply **filed** penalty / forfeit to the unused base |
+| PARTIAL / partially used without `partial_valuation` / residual method | **Fail closed** (`DOMAIN_INPUT_REQUIRED`) — unspecified method ≠ free |
+| `original − used` / coupon-ratio / haversine / MPA-P asserted as method | **Fail closed** — rejected methods |
+| Bare `waiver_code` without typed `waiver_effect` | **≠ free**. Fail closed / DOMAIN_QUESTION — see issue #138 / PR #153 waiver typology. Code alone does not skip penalty |
+
+Do **not** collapse “missing Cat 33” into “missing proration method.” They are different branches.
+
+## Decision tree
+
+```text
+Is the ticket fully unused (no flown coupons)?
+├─ YES → Residual / refundable base = full ticketed base fare.
+│         Apply Cat 31 change fee (5.1) or Cat 33 refund penalty (6.1) SEPARATELY.
+│         Do NOT set residual = base − fee.
+│         Cat 33 absent / unmatched → penalty 0 (free). Bare waiver ≠ free.
+│
+└─ NO (partially used)
+   ├─ Explicit method PUBLISHED_FARE and caller supplies unused (+ flown) amounts?
+   │  ├─ YES → unused_base from caller; apply Cat 33 penalty to unused_base
+   │  │         (or free if no Cat 33 / no match)
+   │  └─ amounts missing → DOMAIN_INPUT_REQUIRED
+   │
+   ├─ Explicit method CARRIER_SPECIFIC and caller supplies carrier-valued amounts?
+   │  ├─ YES → use as filed; apply Cat 33 penalty as above
+   │  └─ amounts / method details missing → DOMAIN_INPUT_REQUIRED
+   │
+   └─ Method unspecified / only “original − used” asserted
+      → DOMAIN_INPUT_REQUIRED (fail closed)
+         NOTE: this is NOT the Cat 33 no-match free path
+```
+
+### Explicitly out of scope for passenger agents
+
+- **MPA-P** (Multilateral Proration Agreement – Passenger) and Prorate Manual / PFM data — **interline settlement between airlines**, not passenger residual.
+- Invented mileage tables, haversine splits, or equal coupon ratios.
+- Committing paid THB / ATPCO DA text into the repo.
+
+## Tax handling on partials
+
+Taxes are **not** the same as base fare residual.
+
+1. Identify which tax amounts remain **unused** after the flown sectors (per tax code).
+2. Cat 33 / regulatory rules may require full refund of some taxes even when base is reduced; others follow unused-sector valuation.
+3. Do **not** invent a coupon-ratio tax split. Caller must supply unused tax breakdown with `PUBLISHED_FARE` or `CARRIER_SPECIFIC`.
+4. Open: per-code matrices remain `DOMAIN_QUESTION` until carrier/tax tables are ingested.
+
+## Conjunction tickets (Agent 6.1)
+
+Conjunction sets are **all-or-none** for refund: you cannot partially refund one document in the set while leaving others. Agent 6.1 already rejects `refund_type: PARTIAL` when `conjunction_tickets` is non-empty.
+
+**No known exception** is recorded in this KB. If a market documents an exception, open a `DOMAIN_QUESTION` with the market and carrier citation — do not code an exception here.
+
+Exchange (5.2) must reference **all** ticket numbers in a conjunction set when exchanging; residual spans the conjunction fare, not a single coupon.
+
+## Proposed agent interfaces (fail closed on method; free on Cat 33 no-match)
+
+```ts
+type PassengerResidualMethod =
+  | 'FULLY_UNUSED'       // no flown coupons
+  | 'PUBLISHED_FARE'     // unused/flown amounts from published fare for flown sectors
+  | 'CARRIER_SPECIFIC';  // carrier residual amounts supplied (not MPA-P)
+
+interface PartialValuationInput {
+  method: Exclude<PassengerResidualMethod, 'FULLY_UNUSED'>;
+  /** Unused base after published-fare / carrier valuation (decimal string). */
+  unused_base_fare: string;
+  /** Optional audit: flown base from that valuation. */
+  flown_base_fare?: string;
+  /** Unused taxes by code — required for PARTIAL money paths. */
+  unused_taxes: Array<{ code: string; amount: string; currency: string }>;
+}
+```
+
+- **5.1** — fully unused: `residual_value = original base`; change fee separate. Partially used: require `residual_valuation`; else `DOMAIN_INPUT_REQUIRED`.
+- **5.2** — applies caller/5.1 residual; requires `residual_method`; does not recompute residual from `original − change_fee`.
+- **6.1** — `PARTIAL` requires `partial_valuation`; else `DOMAIN_INPUT_REQUIRED`. Cat 33 absent/unmatched → **no penalty** on the unused base (free). No coupon-ratio fallback. Bare `waiver_code` ≠ free.
+
+## Worked examples (made-up amounts)
+
+Amounts below are **illustrative only** — not live tickets, not filed carrier data, not handbook extracts.
+
+### Example A — Fully unused one-way (reissue residual)
+
+- Ticketed base: **USD 450.00**, taxes **USD 120.00**
+- Cat 31 change fee (filed): **USD 200.00**
+- New fare: **USD 550.00**
+
+| Field | Correct | Forbidden |
+| --- | --- | --- |
+| Residual toward new fare | **450.00** (full unused base) | 450 − 200 = 250 |
+| Change fee | **200.00** add-collect | baked into residual |
+| Fare difference | 550 − 450 = **100.00** | — |
+| Typical add-collect (fare + fee, taxes aside) | 100 + 200 = **300.00** | 550 − 250 + 200 = 500 (double-counts fee) |
+
+### Example B — Round-trip partially flown, published fare + Cat 33 penalty
+
+- RT ticketed base: **USD 800.00** (OUT + RTN as one through amount on the ticket)
+- Pax flew OUT only; requests refund of RTN
+- Published OW for flown OUT city pair (caller-supplied): **USD 480.00**
+- Cat 33 filed penalty: **USD 150.00**
+- Unused taxes supplied after tax-code review: **USD 55.00**
+
+| Step | Amount |
+| --- | --- |
+| Flown base (published fare) | 480.00 |
+| Unused base before penalty | 800 − 480 = **320.00** |
+| Cat 33 penalty | 150.00 |
+| Refundable base | 320 − 150 = **170.00** |
+| Refundable tax | **55.00** (supplied — not 50% of original tax) |
+| Net before commission | **225.00** |
+
+### Example B′ — Same itinerary, **no Cat 33 data**
+
+- Same unused base **320.00** via `PUBLISHED_FARE`
+- No `cat33_rules` on input
+
+| Step | Amount |
+| --- | --- |
+| Unused base | 320.00 |
+| Cat 33 penalty | **0.00** (ATPCO no-match free default) |
+| Refundable base | **320.00** |
+
+This is **not** fail-closed. Contrast: omitting `partial_valuation` entirely **is** fail-closed.
+
+Rejected alternatives for the same ticket:
+
+- `800 × 1/2 = 400` coupon split — invented
+- MPA-P / TPM split of the through fare — wrong domain (interline)
+- Haversine share of 800 — invented
+- `800 − "used"` with used undefined — fail closed
+- Bare `waiver_code` ⇒ treat as free — wrong (see waiver typology)
+
+### Example C — One-way multi-coupon partially flown, method missing
+
+- OW base **USD 600.00**, 2 coupons, coupon 1 flown
+- No `partial_valuation` on input
+
+→ Engine returns `DOMAIN_INPUT_REQUIRED` with missing `partial_valuation`. **No** residual number is emitted. (Having or lacking Cat 33 data does not fill in a proration method.)
+
+## Data dependencies (do not invent)
+
+| Dependency | Role | Invented substitute (forbidden) |
+| --- | --- | --- |
+| ATPCO Cat 33 filing | Penalty / eligibility; no-match → free | Hardcoded “industry default” residual math; inventing penalties |
+| IATA Ticketing Handbook (THB) | Cite procedures by name only | Committing paid handbook text; inventing “THB = …” acronyms |
+| Published fare amounts for flown sectors | `PUBLISHED_FARE` unused/flown base | Current-day guess, haversine, coupon ratio |
+| Carrier residual formula (when filed) | `CARRIER_SPECIFIC` path | MPA-P / TPM tables |
+| Per-tax-code unused amounts | Partial tax refund | Pro-rata by coupon count |
+| MPA-P / PFM / TPM | **Not used** for passenger residual | — |
+
+## Open DOMAIN_QUESTIONs
+
+- **DQ-R1** — Per-carrier ingestion of Cat 33 structured data (re-price / calculation options per paid ATPCO DA — cite only, do not commit).
+- **DQ-R2** — Operational source for published-fare flown valuation amounts (GDS informative pricing vs ATPCO fare feed).
+- **DQ-R3** — Tax-code matrix for unused-tax determination on partials (especially YQ/YR and non-refundable airport charges).
+- **DQ-R4** — Any documented market exception to conjunction all-or-none refunds (none known; keep fail closed).
+- **DQ-R5** — Cat 31 residual interactions on **partially used** voluntary changes beyond “unused fare value + separate change fee” (carrier-specific).
+- Waiver identity → typed effect: see issue **#138** / PR **#153** (do not treat bare waiver as free).
diff --git a/packages/agents/exchange/src/change-management/__tests__/change-management.test.ts b/packages/agents/exchange/src/change-management/__tests__/change-management.test.ts
index 5399790..9859c85 100644
--- a/packages/agents/exchange/src/change-management/__tests__/change-management.test.ts
+++ b/packages/agents/exchange/src/change-management/__tests__/change-management.test.ts
@@ -109,11 +109,37 @@ describe('Change Management', () => {
       expect(totalDue).toBeGreaterThan(0);
     });
 
-    it('calculates residual value', async () => {
+    it('calculates residual value as full ticketed base (not original − fee)', async () => {
       const result = await agent.execute({ data: makeInput() });
-      const residual = Number(result.data.assessment.residual_value);
-      expect(residual).toBeGreaterThan(0);
-      expect(residual).toBeLessThanOrEqual(450);
+      expect(result.data.assessment.residual_value).toBe('450.00');
+      expect(result.data.assessment.residual_method).toBe('FULLY_UNUSED');
+      expect(Number(result.data.assessment.change_fee)).toBeGreaterThan(0);
+    });
+
+    it('fail-closed when partially used without residual valuation method', async () => {
+      const result = await agent.execute({
+        data: makeInput({ ticket_usage: 'PARTIALLY_USED' }),
+      });
+      expect(result.data).toMatchObject({ status: 'DOMAIN_INPUT_REQUIRED' });
+      if (!('missing' in result.data)) throw new Error('expected domain sentinel');
+      expect(result.data.missing).toContain('residual_valuation');
+    });
+
+    it('uses PUBLISHED_FARE unused base when residual_valuation supplied', async () => {
+      const result = await agent.execute({
+        data: makeInput({
+          ticket_usage: 'PARTIALLY_USED',
+          residual_valuation: {
+            method: 'PUBLISHED_FARE',
+            unused_base_fare: '320.00',
+            flown_base_fare: '480.00',
+            unused_taxes: [{ code: 'GB', amount: '40.00', currency: 'USD' }],
+          },
+        }),
+      });
+      if ('status' in result.data) throw new Error('unexpected domain sentinel');
+      expect(result.data.assessment.residual_value).toBe('320.00');
+      expect(result.data.assessment.residual_method).toBe('PUBLISHED_FARE');
     });
 
     it('sets action to REISSUE for fare change', async () => {
diff --git a/packages/agents/exchange/src/change-management/change-engine.ts b/packages/agents/exchange/src/change-management/change-engine.ts
index 15dbea0..d6ef99b 100644
--- a/packages/agents/exchange/src/change-management/change-engine.ts
+++ b/packages/agents/exchange/src/change-management/change-engine.ts
@@ -20,16 +20,23 @@
  *    Presence of a waiver code ≠ skip penalty.
  * See docs/knowledge-base/waiver-typology.md.
  *
+ * Residual value (issue #150 / KB partial-refund-residual-value.md):
+ * - FULLY_UNUSED → residual = ticketed base (change fee is separate)
+ * - PARTIALLY_USED → require PUBLISHED_FARE or CARRIER_SPECIFIC valuation
+ * - NEVER residual = original − change fee
+ * - MPA-P / haversine / coupon-ratio are not passenger residual methods
+ *
  * // DOMAIN_QUESTION: per-carrier ATPCO Cat31 data ingestion pipeline.
  * // DOMAIN_QUESTION: DQ-W1 — map free-text waiver codes → WaiverEffect
  * //   (only when a waiver_code is present; not when Cat 31 data is absent).
+ * // DOMAIN_QUESTION: DQ-R5 Cat 31 residual on partially used changes.
  */
 
 import Decimal from 'decimal.js';
-import { AgentInputValidationError } from '@otaip/core';
+import { AgentInputValidationError, domainInputRequired } from '@otaip/core';
 import type {
   ChangeManagementInput,
-  ChangeManagementOutput,
+  ChangeManagementResult,
   ChangeAssessment,
   ChangeFeeRule,
   ChangeAction,
@@ -72,6 +79,60 @@ function isWithinFreeChangeWindow(
   return hoursSinceBooking <= freeChangeHours;
 }
 
+function resolveResidual(
+  input: ChangeManagementInput,
+  originalFare: Decimal,
+):
+  | { ok: true; residual: Decimal; method: 'FULLY_UNUSED' | 'PUBLISHED_FARE' | 'CARRIER_SPECIFIC' }
+  | { ok: false; result: ReturnType<typeof domainInputRequired> } {
+  const usage = input.ticket_usage ?? 'FULLY_UNUSED';
+
+  if (usage === 'FULLY_UNUSED') {
+    return { ok: true, residual: originalFare, method: 'FULLY_UNUSED' };
+  }
+
+  const valuation = input.residual_valuation;
+  if (!valuation) {
+    return {
+      ok: false,
+      result: domainInputRequired({
+        missing: [
+          'residual_valuation',
+          'published_fare_or_carrier_residual_amounts',
+        ],
+        description:
+          'Partially used ticket: passenger residual requires explicit PUBLISHED_FARE or CARRIER_SPECIFIC unused amounts (Cat 33 + IATA Ticketing Handbook practice). Cannot use original−used, MPA-P interline proration, haversine, or coupon-ratio splits. Note: absence of Cat 33 data means free penalty — it does not invent a proration method.',
+        references: [
+          'docs/knowledge-base/partial-refund-residual-value.md',
+          'IATA Ticketing Handbook (THB) — cite by name only',
+          'GitHub issue #150',
+        ],
+      }),
+    };
+  }
+
+  if (valuation.method !== 'PUBLISHED_FARE' && valuation.method !== 'CARRIER_SPECIFIC') {
+    return {
+      ok: false,
+      result: domainInputRequired({
+        missing: ['residual_valuation.method'],
+        description:
+          'Partially used residual method must be PUBLISHED_FARE or CARRIER_SPECIFIC. MPA-P is airline interline settlement, not passenger residual.',
+        references: [
+          'docs/knowledge-base/partial-refund-residual-value.md',
+          'GitHub issue #150',
+        ],
+      }),
+    };
+  }
+
+  return {
+    ok: true,
+    residual: new Decimal(valuation.unused_base_fare),
+    method: valuation.method,
+  };
+}
+
 /**
  * Fail closed only for waiver semantics — never for missing Cat 31 data.
  * Absence of Cat 31 / no matched provision is handled by the ATPCO free default
@@ -84,7 +145,6 @@ export function assertChangeWaiverInput(input: ChangeManagementInput): void {
   if (!hasCode && effect === undefined) return;
 
   if (hasCode && effect === undefined) {
-    // TODO: DOMAIN_QUESTION: DQ-W1 — what is the waiver type and its specific effect?
     throw new AgentInputValidationError(
       AGENT_ID,
       'waiver_effect',
@@ -126,7 +186,6 @@ export function assertChangeWaiverInput(input: ChangeManagementInput): void {
     const classes = input.permitted_booking_classes ?? [];
     const patterns = input.permitted_fare_basis_patterns ?? [];
     if (classes.length === 0 && patterns.length === 0) {
-      // TODO: DOMAIN_QUESTION: DQ-W4 — carrier class-substitution tables
       throw new AgentInputValidationError(
         AGENT_ID,
         'permitted_booking_classes',
@@ -195,7 +254,6 @@ function applyWaiverToFee(
     }
     case 'CHANGE_REFUND_FORM':
     case 'CHANGE_REBOOKING_CLASS':
-      // Constraint only — filed Cat 31 charge still applies
       return filedFee;
     default:
       throw new AgentInputValidationError(
@@ -206,7 +264,7 @@ function applyWaiverToFee(
   }
 }
 
-export function assessChange(input: ChangeManagementInput): ChangeManagementOutput {
+export function assessChange(input: ChangeManagementInput): ChangeManagementResult {
   assertChangeWaiverInput(input);
 
   const now = currentTime(input);
@@ -218,7 +276,6 @@ export function assessChange(input: ChangeManagementInput): ChangeManagementOutp
 
   const usDot24h = assessUsDot24Hour(input, now);
 
-  // Reject path applies only when filed rules say so.
   if (isRejectFare(input.cat31_rules, orig.fare_basis)) {
     const assessment: ChangeAssessment = {
       original_ticket_number: orig.ticket_number,
@@ -229,6 +286,7 @@ export function assessChange(input: ChangeManagementInput): ChangeManagementOutp
       fare_difference: '0.00',
       additional_collection: '0.00',
       residual_value: '0.00',
+      residual_method: 'FULLY_UNUSED',
       forfeited_amount: orig.base_fare,
       tax_difference: '0.00',
       total_due: '0.00',
@@ -241,19 +299,20 @@ export function assessChange(input: ChangeManagementInput): ChangeManagementOutp
     return { assessment, us_dot_24h: usDot24h };
   }
 
+  const originalFare = new Decimal(orig.base_fare);
+  const residualResolved = resolveResidual(input, originalFare);
+  if (!residualResolved.ok) {
+    return residualResolved.result;
+  }
+
   const rule = input.cat31_rules
     ? findMatchingRule(input.cat31_rules.rules, orig.fare_basis)
     : undefined;
 
-  // Penalty source-of-truth:
-  //   1. Filed Cat31 rule for this fare basis  → rule.change_fee
-  //   2. No rule + involuntary / IRROP         → 0
-  //   3. No rule + voluntary                   → 0 (ATPCO public default)
   const changeFeeAmount = rule ? new Decimal(rule.change_fee) : new Decimal('0.00');
   const freeChangeHours = rule?.free_change_hours ?? 0;
   const forfeitOnDowngrade = rule?.forfeit_difference_on_downgrade ?? false;
 
-  // Cat 31 filed free-change window ONLY — not US DOT 24h (§259.5(b)(4)).
   const isFreeChange = isWithinFreeChangeWindow(orig.booking_date, now, freeChangeHours);
 
   let effectiveChangeFee: Decimal;
@@ -274,20 +333,14 @@ export function assessChange(input: ChangeManagementInput): ChangeManagementOutp
     effect === 'IRROP_INVOLUNTARY' ||
     (effect === 'REDUCE_PENALTY' && effectiveChangeFee.equals(0));
 
-  // Fare difference
-  const originalFare = new Decimal(orig.base_fare);
   const newFare = new Decimal(req.new_fare);
+  const residualValue = residualResolved.residual;
   const fareDifference = newFare.minus(originalFare);
 
-  // Tax difference
   const originalTax = new Decimal(orig.total_tax);
   const newTax = new Decimal(req.new_tax);
   const taxDifference = newTax.minus(originalTax);
 
-  // Residual value: original fare minus penalty
-  const residualValue = originalFare.minus(effectiveChangeFee);
-
-  // Additional collection and forfeiture
   let additionalCollection = new Decimal('0.00');
   let forfeitedAmount = new Decimal('0.00');
 
@@ -313,7 +366,9 @@ export function assessChange(input: ChangeManagementInput): ChangeManagementOutp
   }
   if (isFreeChange) summaryParts.push('Free change (within booking window).');
   if (effect === 'ELIMINATE_PENALTY') {
-    summaryParts.push(`Waiver code ${input.waiver_code!} effect ELIMINATE_PENALTY — change fee eliminated.`);
+    summaryParts.push(
+      `Waiver code ${input.waiver_code!} effect ELIMINATE_PENALTY — change fee eliminated.`,
+    );
   } else if (effect === 'REDUCE_PENALTY') {
     summaryParts.push(
       `Waiver code ${input.waiver_code!} effect REDUCE_PENALTY — change fee ${currency} ${effectiveChangeFee.toFixed(2)}.`,
@@ -331,6 +386,8 @@ export function assessChange(input: ChangeManagementInput): ChangeManagementOutp
   }
   if (!rule && !input.cat31_rules)
     summaryParts.push('No Cat31 rules supplied — applying ATPCO default (no charge).');
+  else if (input.cat31_rules && !rule)
+    summaryParts.push('No matching Cat31 provision — applying ATPCO default (no charge).');
   if (effectiveChangeFee.greaterThan(0))
     summaryParts.push(`Change fee: ${currency} ${effectiveChangeFee.toFixed(2)}.`);
   if (additionalCollection.greaterThan(0))
@@ -338,6 +395,9 @@ export function assessChange(input: ChangeManagementInput): ChangeManagementOutp
   if (forfeitedAmount.greaterThan(0))
     summaryParts.push(`Forfeited on downgrade: ${currency} ${forfeitedAmount.toFixed(2)}.`);
   if (taxDue.greaterThan(0)) summaryParts.push(`Tax adjustment: ${currency} ${taxDue.toFixed(2)}.`);
+  summaryParts.push(
+    `Residual (${residualResolved.method}): ${currency} ${residualValue.toFixed(2)}.`,
+  );
   summaryParts.push(`Total due: ${currency} ${totalDue.toFixed(2)}.`);
 
   const assessment: ChangeAssessment = {
@@ -357,6 +417,7 @@ export function assessChange(input: ChangeManagementInput): ChangeManagementOutp
     fare_difference: fareDifference.toFixed(2),
     additional_collection: additionalCollection.toFixed(2),
     residual_value: residualValue.toFixed(2),
+    residual_method: residualResolved.method,
     forfeited_amount: forfeitedAmount.toFixed(2),
     tax_difference: taxDifference.toFixed(2),
     total_due: totalDue.toFixed(2),
diff --git a/packages/agents/exchange/src/change-management/index.ts b/packages/agents/exchange/src/change-management/index.ts
index 9ac8bf1..6c1ef30 100644
--- a/packages/agents/exchange/src/change-management/index.ts
+++ b/packages/agents/exchange/src/change-management/index.ts
@@ -4,20 +4,29 @@
  * ATPCO Category 31 voluntary change assessment: change fees,
  * fare difference, residual value, waiver codes.
  *
+ * Residual: see docs/knowledge-base/partial-refund-residual-value.md
+ * (issue #150). Never residual = original − change fee.
+ *
  * Implements the base Agent interface from @otaip/core.
  */
 
 import type { Agent, AgentInput, AgentOutput, AgentHealthStatus } from '@otaip/core';
-import { AgentNotInitializedError, AgentInputValidationError } from '@otaip/core';
-import type { ChangeManagementInput, ChangeManagementOutput } from './types.js';
+import {
+  AgentNotInitializedError,
+  AgentInputValidationError,
+  isDomainInputRequired,
+} from '@otaip/core';
+import type { ChangeManagementInput, ChangeManagementResult } from './types.js';
 import { assessChange, assertChangeWaiverInput } from './change-engine.js';
 
 const TICKET_NUMBER_RE = /^\d{13}$/;
 const CARRIER_RE = /^[A-Z0-9]{2}$/;
 const PASSENGER_NAME_RE = /^[A-Z][A-Z' -]+\/[A-Z][A-Z' -]+$/;
 const RECORD_LOCATOR_RE = /^[A-Z0-9]{6}$/;
+const VALID_USAGE = new Set(['FULLY_UNUSED', 'PARTIALLY_USED']);
+const VALID_RESIDUAL_METHODS = new Set(['PUBLISHED_FARE', 'CARRIER_SPECIFIC']);
 
-export class ChangeManagement implements Agent<ChangeManagementInput, ChangeManagementOutput> {
+export class ChangeManagement implements Agent<ChangeManagementInput, ChangeManagementResult> {
   readonly id = '5.1';
   readonly name = 'Change Management';
   readonly version = '0.1.0';
@@ -30,7 +39,7 @@ export class ChangeManagement implements Agent<ChangeManagementInput, ChangeMana
 
   async execute(
     input: AgentInput<ChangeManagementInput>,
-  ): Promise<AgentOutput<ChangeManagementOutput>> {
+  ): Promise<AgentOutput<ChangeManagementResult>> {
     if (!this.initialized) {
       throw new AgentNotInitializedError(this.id);
     }
@@ -39,6 +48,23 @@ export class ChangeManagement implements Agent<ChangeManagementInput, ChangeMana
 
     const result = assessChange(input.data);
 
+    if (isDomainInputRequired(result)) {
+      return {
+        data: result,
+        confidence: 0,
+        warnings: [
+          `DOMAIN_INPUT_REQUIRED: ${result.description}`,
+          ...result.missing.map((m) => `missing: ${m}`),
+        ],
+        metadata: {
+          agent_id: this.id,
+          agent_version: this.version,
+          original_ticket: input.data.original_ticket.ticket_number,
+          status: 'DOMAIN_INPUT_REQUIRED',
+        },
+      };
+    }
+
     const warnings: string[] = [];
     if (result.assessment.action === 'REJECT') {
       warnings.push('Change not permitted for this fare type.');
@@ -60,6 +86,7 @@ export class ChangeManagement implements Agent<ChangeManagementInput, ChangeMana
         action: result.assessment.action,
         total_due: result.assessment.total_due,
         fee_waived: result.assessment.fee_waived,
+        residual_method: result.assessment.residual_method,
         us_dot_24h_eligible: result.us_dot_24h.eligible,
         us_dot_24h_remedy: result.us_dot_24h.carrier_remedy,
       },
@@ -124,17 +151,52 @@ export class ChangeManagement implements Agent<ChangeManagementInput, ChangeMana
     }
 
     assertChangeWaiverInput(data);
+
+    if (data.ticket_usage !== undefined && !VALID_USAGE.has(data.ticket_usage)) {
+      throw new AgentInputValidationError(
+        this.id,
+        'ticket_usage',
+        'Must be FULLY_UNUSED or PARTIALLY_USED.',
+      );
+    }
+
+    if (data.residual_valuation) {
+      const v = data.residual_valuation;
+      if (!VALID_RESIDUAL_METHODS.has(v.method)) {
+        throw new AgentInputValidationError(
+          this.id,
+          'residual_valuation.method',
+          'Must be PUBLISHED_FARE or CARRIER_SPECIFIC. MPA-P / original−used / coupon-ratio are rejected.',
+        );
+      }
+      if (!v.unused_base_fare || isNaN(Number(v.unused_base_fare))) {
+        throw new AgentInputValidationError(
+          this.id,
+          'residual_valuation.unused_base_fare',
+          'Must be a valid decimal string.',
+        );
+      }
+      if (!v.unused_taxes || !Array.isArray(v.unused_taxes)) {
+        throw new AgentInputValidationError(
+          this.id,
+          'residual_valuation.unused_taxes',
+          'Unused tax breakdown is required for partial residual valuation.',
+        );
+      }
+    }
   }
 }
 
 export type {
   ChangeManagementInput,
   ChangeManagementOutput,
+  ChangeManagementResult,
   ChangeAssessment,
   OriginalTicketSummary,
   RequestedItinerary,
   ChangeFeeRule,
   ChangeAction,
+  TicketUsage,
   UsDot24HourRemedy,
   UsDot24HourBookingChannel,
   UsDot24HourIneligibilityReason,
diff --git a/packages/agents/exchange/src/change-management/types.ts b/packages/agents/exchange/src/change-management/types.ts
index bbe5235..4075972 100644
--- a/packages/agents/exchange/src/change-management/types.ts
+++ b/packages/agents/exchange/src/change-management/types.ts
@@ -10,10 +10,19 @@
  * Waiver typology: docs/knowledge-base/waiver-typology.md
  * - No Cat 31 data / no match → free change (ATPCO default; not fail-closed).
  * - Bare waiver_code without waiver_effect → fail closed (≠ skip penalty).
+ *
+ * Residual value: docs/knowledge-base/partial-refund-residual-value.md (issue #150)
+ * - Never residual = original − change fee; partials require PUBLISHED_FARE or
+ *   CARRIER_SPECIFIC valuation (MPA-P is not passenger residual).
  */
 
+import type { DomainInputRequired, PassengerPartialValuation } from '@otaip/core';
+
 export type ChangeAction = 'REISSUE' | 'REBOOK' | 'REJECT';
 
+/** Whether any coupon has been flown. */
+export type TicketUsage = 'FULLY_UNUSED' | 'PARTIALLY_USED';
+
 /**
  * Carrier election under 14 CFR §259.5(b)(4).
  * Carriers choose ONE compliance path — not both.
@@ -227,8 +236,15 @@ export interface ChangeAssessment {
   fare_difference: string;
   /** Additional collection required (decimal string, "0.00" if none) */
   additional_collection: string;
-  /** Residual value: original fare minus penalty, available for reissue (decimal string) */
+  /**
+   * Residual value available for reissue (decimal string).
+   * Fully unused: ticketed base fare (change fee is separate).
+   * Partially used: unused base from PUBLISHED_FARE / CARRIER_SPECIFIC valuation.
+   * Never original − change fee.
+   */
   residual_value: string;
+  /** Valuation method used for residual_value */
+  residual_method: 'FULLY_UNUSED' | 'PUBLISHED_FARE' | 'CARRIER_SPECIFIC';
   /** Forfeited amount on non-refundable downgrade (decimal string, "0.00" if none) */
   forfeited_amount: string;
   /** Tax difference (decimal string) */
@@ -319,6 +335,16 @@ export interface ChangeManagementInput {
    * See docs/knowledge-base/us-dot-24-hour-reservation.md.
    */
   us_dot_24h?: UsDot24HourContext;
+  /**
+   * Ticket usage. Defaults to FULLY_UNUSED when omitted.
+   * PARTIALLY_USED requires `residual_valuation` (PUBLISHED_FARE or carrier).
+   */
+  ticket_usage?: TicketUsage;
+  /**
+   * Unused residual after published-fare / carrier valuation.
+   * Required when ticket_usage is PARTIALLY_USED. See KB issue #150.
+   */
+  residual_valuation?: PassengerPartialValuation;
 }
 
 export interface ChangeManagementOutput {
@@ -330,3 +356,6 @@ export interface ChangeManagementOutput {
    */
   us_dot_24h: UsDot24HourAssessment;
 }
+
+/** Successful assessment or fail-closed domain sentinel. */
+export type ChangeManagementResult = ChangeManagementOutput | DomainInputRequired;
diff --git a/packages/agents/exchange/src/exchange-reissue/__tests__/exchange-reissue.test.ts b/packages/agents/exchange/src/exchange-reissue/__tests__/exchange-reissue.test.ts
index a00aa1b..83f0997 100644
--- a/packages/agents/exchange/src/exchange-reissue/__tests__/exchange-reissue.test.ts
+++ b/packages/agents/exchange/src/exchange-reissue/__tests__/exchange-reissue.test.ts
@@ -108,7 +108,8 @@ function makeInput(overrides: Partial<ExchangeReissueInput> = {}): ExchangeReiss
     record_locator: 'ABC123',
     original_base_fare: '450.00',
     change_fee: '200.00',
-    residual_value: '250.00',
+    residual_value: '450.00',
+    residual_method: 'FULLY_UNUSED',
     new_segments: [
       {
         carrier: 'BA',
@@ -143,7 +144,8 @@ describe('Exchange/Reissue', () => {
   describe('Residual value application', () => {
     it('applies residual value to new fare', async () => {
       const result = await agent.execute({ data: makeInput() });
-      expect(result.data.reissue.exchange_audit.residual_applied).toBe('250.00');
+      expect(result.data.reissue.exchange_audit.residual_applied).toBe('450.00');
+      expect(result.data.reissue.exchange_audit.residual_method).toBe('FULLY_UNUSED');
     });
 
     it('calculates additional collection (new fare - residual + change fee + new taxes)', async () => {
diff --git a/packages/agents/exchange/src/exchange-reissue/index.ts b/packages/agents/exchange/src/exchange-reissue/index.ts
index b70972a..c2d687b 100644
--- a/packages/agents/exchange/src/exchange-reissue/index.ts
+++ b/packages/agents/exchange/src/exchange-reissue/index.ts
@@ -11,8 +11,8 @@
  */
 
 import type { Agent, AgentInput, AgentOutput, AgentHealthStatus } from '@otaip/core';
-import { AgentNotInitializedError, AgentInputValidationError } from '@otaip/core';
-import type { ExchangeReissueInput, ExchangeReissueOutput } from './types.js';
+import { AgentNotInitializedError, AgentInputValidationError, isDomainInputRequired } from '@otaip/core';
+import type { ExchangeReissueInput, ExchangeReissueResult } from './types.js';
 import { processReissue } from './reissue-engine.js';
 import {
   TaxCarryforwardRuleMissingError,
@@ -32,7 +32,9 @@ const VALID_NATURE = new Set(['TRANSPORT', 'SALES']);
 const VALID_MIN_GEO = new Set(['SAME_AIRPORT', 'SAME_CITY']);
 const VALID_EXPIRED_ACTION = new Set(['RECALCULATE', 'FORFEIT']);
 
-export class ExchangeReissue implements Agent<ExchangeReissueInput, ExchangeReissueOutput> {
+const VALID_RESIDUAL_METHODS = new Set(['FULLY_UNUSED', 'PUBLISHED_FARE', 'CARRIER_SPECIFIC']);
+
+export class ExchangeReissue implements Agent<ExchangeReissueInput, ExchangeReissueResult> {
   readonly id = '5.2';
   readonly name = 'Exchange/Reissue';
   readonly version = '0.2.0';
@@ -45,14 +47,14 @@ export class ExchangeReissue implements Agent<ExchangeReissueInput, ExchangeReis
 
   async execute(
     input: AgentInput<ExchangeReissueInput>,
-  ): Promise<AgentOutput<ExchangeReissueOutput>> {
+  ): Promise<AgentOutput<ExchangeReissueResult>> {
     if (!this.initialized) {
       throw new AgentNotInitializedError(this.id);
     }
 
     this.validateInput(input.data);
 
-    let result: ExchangeReissueOutput;
+    let result: ExchangeReissueResult;
     try {
       result = processReissue(input.data);
     } catch (err) {
@@ -66,6 +68,23 @@ export class ExchangeReissue implements Agent<ExchangeReissueInput, ExchangeReis
       throw err;
     }
 
+    if (isDomainInputRequired(result)) {
+      return {
+        data: result,
+        confidence: 0,
+        warnings: [
+          `DOMAIN_INPUT_REQUIRED: ${result.description}`,
+          ...result.missing.map((m) => `missing: ${m}`),
+        ],
+        metadata: {
+          agent_id: this.id,
+          agent_version: this.version,
+          original_ticket: input.data.original_ticket_number,
+          status: 'DOMAIN_INPUT_REQUIRED',
+        },
+      };
+    }
+
     const warnings: string[] = [];
     if (result.credit_amount !== '0.00') {
       warnings.push(
@@ -95,6 +114,7 @@ export class ExchangeReissue implements Agent<ExchangeReissueInput, ExchangeReis
         additional_collection: result.additional_collection,
         credit_amount: result.credit_amount,
         tax_decision_count: result.tax_decisions.length,
+        residual_method: result.reissue.exchange_audit.residual_method,
       },
     };
   }
@@ -171,6 +191,20 @@ export class ExchangeReissue implements Agent<ExchangeReissueInput, ExchangeReis
     if (data.gds && !VALID_GDS.has(data.gds)) {
       throw new AgentInputValidationError(this.id, 'gds', `Invalid GDS: ${data.gds}`);
     }
+    if (!data.residual_method || !VALID_RESIDUAL_METHODS.has(data.residual_method)) {
+      throw new AgentInputValidationError(
+        this.id,
+        'residual_method',
+        'Must be FULLY_UNUSED, PUBLISHED_FARE, or CARRIER_SPECIFIC. original−change-fee / MPA-P / coupon-ratio are rejected.',
+      );
+    }
+    if (!data.residual_value || isNaN(Number(data.residual_value))) {
+      throw new AgentInputValidationError(
+        this.id,
+        'residual_value',
+        'Must be a valid decimal string.',
+      );
+    }
     if (data.conjunction_originals) {
       for (const ct of data.conjunction_originals) {
         if (!TICKET_NUMBER_RE.test(ct)) {
@@ -281,6 +315,7 @@ export class ExchangeReissue implements Agent<ExchangeReissueInput, ExchangeReis
 export type {
   ExchangeReissueInput,
   ExchangeReissueOutput,
+  ExchangeReissueResult,
   ReissueRecord,
   ReissuedCoupon,
   ExchangeAuditTrail,
diff --git a/packages/agents/exchange/src/exchange-reissue/reissue-engine.ts b/packages/agents/exchange/src/exchange-reissue/reissue-engine.ts
index dc3ed4d..0a16df5 100644
--- a/packages/agents/exchange/src/exchange-reissue/reissue-engine.ts
+++ b/packages/agents/exchange/src/exchange-reissue/reissue-engine.ts
@@ -4,12 +4,16 @@
  * Tax carryforward: per-tax CARRY | RECALCULATE | FORFEIT.
  * See docs/knowledge-base/tax-carryforward-reissue.md
  * Same O&D boolean is not used for tax decisions. IROE ≠ ICER (no FX here).
+ *
+ * Residual is applied as supplied with an explicit residual_method.
+ * Never recomputes residual as original − change fee (issue #150).
  */
 
 import Decimal from 'decimal.js';
+import { domainInputRequired } from '@otaip/core';
 import type {
   ExchangeReissueInput,
-  ExchangeReissueOutput,
+  ExchangeReissueResult,
   ReissueRecord,
   ReissuedCoupon,
   TaxItem,
@@ -254,7 +258,35 @@ function buildExchangeCommands(
 // Main engine
 // ---------------------------------------------------------------------------
 
-export function processReissue(input: ExchangeReissueInput): ExchangeReissueOutput {
+export function processReissue(input: ExchangeReissueInput): ExchangeReissueResult {
+  if (!input.residual_method) {
+    return domainInputRequired({
+      missing: ['residual_method'],
+      description:
+        'Exchange/reissue requires residual_method (FULLY_UNUSED, PUBLISHED_FARE, or CARRIER_SPECIFIC). Residual must not be invented as original − change fee. MPA-P is not passenger residual.',
+      references: [
+        'docs/knowledge-base/partial-refund-residual-value.md',
+        'GitHub issue #150',
+      ],
+    });
+  }
+
+  if (
+    input.residual_method !== 'FULLY_UNUSED' &&
+    input.residual_method !== 'PUBLISHED_FARE' &&
+    input.residual_method !== 'CARRIER_SPECIFIC'
+  ) {
+    return domainInputRequired({
+      missing: ['residual_method'],
+      description:
+        'residual_method must be FULLY_UNUSED, PUBLISHED_FARE, or CARRIER_SPECIFIC. Rejected: original−change-fee, MPA-P, haversine, coupon-ratio.',
+      references: [
+        'docs/knowledge-base/partial-refund-residual-value.md',
+        'GitHub issue #150',
+      ],
+    });
+  }
+
   const prefix = resolvePrefix(input);
   const issueDate = input.issue_date ?? new Date().toISOString().slice(0, 10);
   const serial = generateSerial(input.record_locator, input.passenger_name);
@@ -309,6 +341,7 @@ export function processReissue(input: ExchangeReissueInput): ExchangeReissueOutp
     exchange_indicator: 'E',
     change_fee_paid: changeFee.toFixed(2),
     residual_applied: residualValue.toFixed(2),
+    residual_method: input.residual_method,
     additional_collection: additionalCollection.toFixed(2),
     taxes_carried_forward: carriedForward,
     taxes_new: newTaxes,
diff --git a/packages/agents/exchange/src/exchange-reissue/types.ts b/packages/agents/exchange/src/exchange-reissue/types.ts
index 1bc28a8..bdde0fd 100644
--- a/packages/agents/exchange/src/exchange-reissue/types.ts
+++ b/packages/agents/exchange/src/exchange-reissue/types.ts
@@ -6,8 +6,13 @@
  *
  * Tax carryforward: see docs/knowledge-base/tax-carryforward-reissue.md
  * Same O&D alone is insufficient. Decisions are per tax code.
+ *
+ * Residual: explicit residual_method required — never original − change fee
+ * (docs/knowledge-base/partial-refund-residual-value.md, issue #150).
  */
 
+import type { DomainInputRequired, PassengerResidualMethod } from '@otaip/core';
+
 export type ExchangeGdsSystem = 'AMADEUS' | 'SABRE' | 'TRAVELPORT';
 
 export interface ExchangeSegment {
@@ -131,6 +136,8 @@ export interface ExchangeAuditTrail {
   change_fee_paid: string;
   /** Residual value applied (decimal string) */
   residual_applied: string;
+  /** Valuation method for residual_applied (from Agent 5.1) */
+  residual_method: PassengerResidualMethod;
   /** Additional collection (decimal string) */
   additional_collection: string;
   /** Taxes carried forward from original ticket */
@@ -233,6 +240,10 @@ export interface ExchangeReissueInput {
   change_fee: string;
   /** Residual value (decimal string, from Agent 5.1) */
   residual_value: string;
+  /**
+   * How residual_value was determined. Required — never infer original − change fee.
+   */
+  residual_method: PassengerResidualMethod;
   /** Waiver code (if applied in Agent 5.1) */
   waiver_code?: string;
   /** New segments */
@@ -281,3 +292,6 @@ export interface ExchangeReissueOutput {
   /** Per-tax carryforward decisions (also on exchange_audit) */
   tax_decisions: TaxCarryforwardDecision[];
 }
+
+/** Successful reissue or fail-closed domain sentinel. */
+export type ExchangeReissueResult = ExchangeReissueOutput | DomainInputRequired;
diff --git a/packages/agents/exchange/src/index.ts b/packages/agents/exchange/src/index.ts
index 27e4442..f937815 100644
--- a/packages/agents/exchange/src/index.ts
+++ b/packages/agents/exchange/src/index.ts
@@ -8,11 +8,13 @@ export { ChangeManagement } from './change-management/index.js';
 export type {
   ChangeManagementInput,
   ChangeManagementOutput,
+  ChangeManagementResult,
   ChangeAssessment,
   OriginalTicketSummary,
   RequestedItinerary,
   ChangeFeeRule,
   ChangeAction,
+  TicketUsage,
   UsDot24HourRemedy,
   UsDot24HourBookingChannel,
   UsDot24HourIneligibilityReason,
@@ -36,6 +38,7 @@ export {
 export type {
   ExchangeReissueInput,
   ExchangeReissueOutput,
+  ExchangeReissueResult,
   ReissueRecord,
   ReissuedCoupon,
   ExchangeAuditTrail,
diff --git a/packages/agents/exchange/src/self-service-rebooking/index.ts b/packages/agents/exchange/src/self-service-rebooking/index.ts
index 172512c..59e7c29 100644
--- a/packages/agents/exchange/src/self-service-rebooking/index.ts
+++ b/packages/agents/exchange/src/self-service-rebooking/index.ts
@@ -15,7 +15,11 @@
 
 import Decimal from 'decimal.js';
 import type { Agent, AgentHealthStatus, AgentInput, AgentOutput, SearchOffer } from '@otaip/core';
-import { AgentInputValidationError, AgentNotInitializedError } from '@otaip/core';
+import {
+  AgentInputValidationError,
+  AgentNotInitializedError,
+  isDomainInputRequired,
+} from '@otaip/core';
 import { AvailabilitySearch } from '@otaip/agents-search';
 import type { AvailabilitySearchInput } from '@otaip/agents-search';
 import { ChangeManagement } from '../change-management/index.js';
@@ -148,7 +152,7 @@ export class SelfServiceRebookingAgent
         })
         .catch(() => null);
 
-      if (!assessment) continue;
+      if (!assessment || isDomainInputRequired(assessment.data)) continue;
       const a = assessment.data.assessment;
 
       // Skip REJECTed candidates entirely (noted in count but not returned).
diff --git a/packages/agents/settlement/src/index.ts b/packages/agents/settlement/src/index.ts
index 68250ce..29c5345 100644
--- a/packages/agents/settlement/src/index.ts
+++ b/packages/agents/settlement/src/index.ts
@@ -8,6 +8,7 @@ export { RefundProcessing } from './refund-processing/index.js';
 export type {
   RefundProcessingInput,
   RefundProcessingOutput,
+  RefundProcessingResult,
   RefundRecord,
   RefundAuditTrail,
   RefundType,
diff --git a/packages/agents/settlement/src/refund-processing/__tests__/refund-processing.test.ts b/packages/agents/settlement/src/refund-processing/__tests__/refund-processing.test.ts
index 631810f..fd8ee64 100644
--- a/packages/agents/settlement/src/refund-processing/__tests__/refund-processing.test.ts
+++ b/packages/agents/settlement/src/refund-processing/__tests__/refund-processing.test.ts
@@ -201,7 +201,7 @@ describe('Refund Processing', () => {
   });
 
   describe('Partial refund', () => {
-    it('prorates fare for partial refund', async () => {
+    it('fail-closed without partial_valuation method', async () => {
       const coupons: CouponRefundItem[] = [
         { coupon_number: 1, status: 'O', refundable: true },
         { coupon_number: 2, status: 'O', refundable: true },
@@ -209,18 +209,80 @@ describe('Refund Processing', () => {
       const result = await agent.execute({
         data: makeInput({ refund_type: 'PARTIAL', coupons_to_refund: coupons }),
       });
-      // 2 of 4 coupons = 50% of base fare
-      expect(Number(result.data.refund.audit.original_base_fare)).toBe(450);
-      expect(result.data.refund.audit.coupons_refunded).toEqual([1, 2]);
+      expect(result.data).toMatchObject({ status: 'DOMAIN_INPUT_REQUIRED' });
+      if (!('missing' in result.data)) throw new Error('expected domain sentinel');
+      expect(result.data.missing).toContain('partial_valuation');
+      expect(result.data.description).toMatch(/THB|IATA Ticketing Handbook/i);
+      expect(result.data.description).toMatch(/MPA-P/);
     });
 
-    it('prorates taxes for partial refund', async () => {
+    it('applies Cat 33 penalty to PUBLISHED_FARE unused base (not coupon-ratio)', async () => {
+      const coupons: CouponRefundItem[] = [{ coupon_number: 2, status: 'O', refundable: true }];
+      const result = await agent.execute({
+        data: makeInput({
+          base_fare: '800.00',
+          refund_type: 'PARTIAL',
+          coupons_to_refund: coupons,
+          total_coupons: 2,
+          fare_basis: 'HOWUS',
+          partial_valuation: {
+            method: 'PUBLISHED_FARE',
+            unused_base_fare: '320.00',
+            flown_base_fare: '480.00',
+            unused_taxes: [{ code: 'GB', amount: '55.00', currency: 'USD' }],
+          },
+        }),
+      });
+      if ('status' in result.data) throw new Error('unexpected domain sentinel');
+      expect(result.data.refund.audit.residual_method).toBe('PUBLISHED_FARE');
+      expect(result.data.refund.audit.flown_base_fare).toBe('480.00');
+      expect(result.data.refund.tax_refund).toBe('55.00');
+      expect(result.data.refund.penalty_applied).toBe('200.00');
+      expect(result.data.refund.base_fare_refund).toBe('120.00');
+    });
+
+    it('no Cat 33 data + PUBLISHED_FARE: free penalty on unused base (not fail-closed)', async () => {
+      const coupons: CouponRefundItem[] = [{ coupon_number: 2, status: 'O', refundable: true }];
+      const result = await agent.execute({
+        data: makeInput({
+          base_fare: '800.00',
+          refund_type: 'PARTIAL',
+          coupons_to_refund: coupons,
+          total_coupons: 2,
+          cat33_rules: undefined,
+          partial_valuation: {
+            method: 'PUBLISHED_FARE',
+            unused_base_fare: '320.00',
+            flown_base_fare: '480.00',
+            unused_taxes: [{ code: 'GB', amount: '55.00', currency: 'USD' }],
+          },
+        }),
+      });
+      if ('status' in result.data) throw new Error('unexpected domain sentinel');
+      expect(result.data.refund.penalty_applied).toBe('0.00');
+      expect(result.data.refund.base_fare_refund).toBe('320.00');
+    });
+
+    it('does not invent coupon-ratio tax when unused taxes are supplied', async () => {
       const coupons: CouponRefundItem[] = [{ coupon_number: 3, status: 'O', refundable: true }];
       const result = await agent.execute({
-        data: makeInput({ refund_type: 'PARTIAL', coupons_to_refund: coupons }),
+        data: makeInput({
+          refund_type: 'PARTIAL',
+          coupons_to_refund: coupons,
+          cat33_rules: undefined,
+          partial_valuation: {
+            method: 'PUBLISHED_FARE',
+            unused_base_fare: '112.50',
+            unused_taxes: [
+              { code: 'GB', amount: '20.00', currency: 'USD' },
+              { code: 'US', amount: '5.00', currency: 'USD' },
+            ],
+          },
+        }),
       });
-      // 1 of 4 coupons = 25% of taxes
-      expect(result.data.refund.tax_refund).toBe('30.00');
+      if ('status' in result.data) throw new Error('unexpected domain sentinel');
+      expect(result.data.refund.tax_refund).toBe('25.00');
+      expect(result.data.refund.base_fare_refund).toBe('112.50');
     });
 
     it('only refunds coupons marked as refundable', async () => {
@@ -229,9 +291,20 @@ describe('Refund Processing', () => {
         { coupon_number: 2, status: 'L', refundable: false },
       ];
       const result = await agent.execute({
-        data: makeInput({ refund_type: 'PARTIAL', coupons_to_refund: coupons }),
+        data: makeInput({
+          refund_type: 'PARTIAL',
+          coupons_to_refund: coupons,
+          cat33_rules: undefined,
+          partial_valuation: {
+            method: 'CARRIER_SPECIFIC',
+            unused_base_fare: '200.00',
+            unused_taxes: [{ code: 'GB', amount: '10.00', currency: 'USD' }],
+          },
+        }),
       });
+      if ('status' in result.data) throw new Error('unexpected domain sentinel');
       expect(result.data.refund.audit.coupons_refunded).toEqual([1]);
+      expect(result.data.refund.audit.residual_method).toBe('CARRIER_SPECIFIC');
     });
   });
 
@@ -365,11 +438,15 @@ describe('Refund Processing', () => {
         data: makeInput({
           refund_type: 'PARTIAL',
           coupons_to_refund: coupons,
-          waiver_code: 'W',
-          waiver_effect: 'ELIMINATE_PENALTY',
+          cat33_rules: undefined,
+          partial_valuation: {
+            method: 'PUBLISHED_FARE',
+            unused_base_fare: '112.50',
+            unused_taxes: [{ code: 'GB', amount: '10.00', currency: 'USD' }],
+          },
         }),
       });
-      // 1/4 = 25% of base = 112.50 refunded → commission recall = 31.50 * 112.50/450 = 7.875 → 7.88
+      if ('status' in result.data) throw new Error('unexpected domain sentinel');
       expect(Number(result.data.commission_recalled)).toBeGreaterThan(0);
       expect(Number(result.data.commission_recalled)).toBeLessThan(31.5);
     });
diff --git a/packages/agents/settlement/src/refund-processing/index.ts b/packages/agents/settlement/src/refund-processing/index.ts
index 31727be..f1696c6 100644
--- a/packages/agents/settlement/src/refund-processing/index.ts
+++ b/packages/agents/settlement/src/refund-processing/index.ts
@@ -4,12 +4,19 @@
  * ATPCO Category 33 refund processing: penalty application,
  * commission recall, BSP/ARC reporting, conjunction ticket handling.
  *
+ * Partial residual: Cat 33 + THB — see
+ * docs/knowledge-base/partial-refund-residual-value.md (issue #150).
+ *
  * Implements the base Agent interface from @otaip/core.
  */
 
 import type { Agent, AgentInput, AgentOutput, AgentHealthStatus } from '@otaip/core';
-import { AgentNotInitializedError, AgentInputValidationError } from '@otaip/core';
-import type { RefundProcessingInput, RefundProcessingOutput } from './types.js';
+import {
+  AgentNotInitializedError,
+  AgentInputValidationError,
+  isDomainInputRequired,
+} from '@otaip/core';
+import type { RefundProcessingInput, RefundProcessingResult } from './types.js';
 import { processRefund, assertRefundWaiverInput } from './refund-engine.js';
 
 const TICKET_NUMBER_RE = /^\d{13}$/;
@@ -18,8 +25,9 @@ const PASSENGER_NAME_RE = /^[A-Z][A-Z' -]+\/[A-Z][A-Z' -]+$/;
 const RECORD_LOCATOR_RE = /^[A-Z0-9]{6}$/;
 const VALID_REFUND_TYPES = new Set(['FULL', 'PARTIAL', 'TAX_ONLY']);
 const VALID_SETTLEMENT = new Set(['BSP', 'ARC']);
+const VALID_PARTIAL_METHODS = new Set(['PUBLISHED_FARE', 'CARRIER_SPECIFIC']);
 
-export class RefundProcessing implements Agent<RefundProcessingInput, RefundProcessingOutput> {
+export class RefundProcessing implements Agent<RefundProcessingInput, RefundProcessingResult> {
   readonly id = '6.1';
   readonly name = 'Refund Processing';
   readonly version = '0.1.0';
@@ -32,7 +40,7 @@ export class RefundProcessing implements Agent<RefundProcessingInput, RefundProc
 
   async execute(
     input: AgentInput<RefundProcessingInput>,
-  ): Promise<AgentOutput<RefundProcessingOutput>> {
+  ): Promise<AgentOutput<RefundProcessingResult>> {
     if (!this.initialized) {
       throw new AgentNotInitializedError(this.id);
     }
@@ -41,6 +49,24 @@ export class RefundProcessing implements Agent<RefundProcessingInput, RefundProc
 
     const result = processRefund(input.data);
 
+    if (isDomainInputRequired(result)) {
+      return {
+        data: result,
+        confidence: 0,
+        warnings: [
+          `DOMAIN_INPUT_REQUIRED: ${result.description}`,
+          ...result.missing.map((m) => `missing: ${m}`),
+        ],
+        metadata: {
+          agent_id: this.id,
+          agent_version: this.version,
+          ticket_number: input.data.ticket_number,
+          refund_type: input.data.refund_type,
+          status: 'DOMAIN_INPUT_REQUIRED',
+        },
+      };
+    }
+
     const warnings: string[] = [];
     if (result.refund.penalty_applied !== '0.00') {
       warnings.push(
@@ -73,6 +99,7 @@ export class RefundProcessing implements Agent<RefundProcessingInput, RefundProc
         net_refund: result.net_refund_amount,
         penalty: result.refund.penalty_applied,
         settlement_system: input.data.settlement_system,
+        residual_method: result.refund.audit.residual_method,
       },
     };
   }
@@ -140,6 +167,30 @@ export class RefundProcessing implements Agent<RefundProcessingInput, RefundProc
         'Required for PARTIAL refund.',
       );
     }
+    if (data.partial_valuation) {
+      const v = data.partial_valuation;
+      if (!VALID_PARTIAL_METHODS.has(v.method)) {
+        throw new AgentInputValidationError(
+          this.id,
+          'partial_valuation.method',
+          'Must be PUBLISHED_FARE or CARRIER_SPECIFIC. MPA-P / original−used / coupon-ratio are rejected.',
+        );
+      }
+      if (!v.unused_base_fare || isNaN(Number(v.unused_base_fare))) {
+        throw new AgentInputValidationError(
+          this.id,
+          'partial_valuation.unused_base_fare',
+          'Must be a valid decimal string.',
+        );
+      }
+      if (!v.unused_taxes || !Array.isArray(v.unused_taxes)) {
+        throw new AgentInputValidationError(
+          this.id,
+          'partial_valuation.unused_taxes',
+          'Unused tax breakdown is required (no coupon-ratio tax invention).',
+        );
+      }
+    }
     if (data.conjunction_tickets) {
       for (const ct of data.conjunction_tickets) {
         if (!TICKET_NUMBER_RE.test(ct)) {
@@ -166,6 +217,7 @@ export class RefundProcessing implements Agent<RefundProcessingInput, RefundProc
 export type {
   RefundProcessingInput,
   RefundProcessingOutput,
+  RefundProcessingResult,
   RefundRecord,
   RefundAuditTrail,
   RefundType,
diff --git a/packages/agents/settlement/src/refund-processing/refund-engine.ts b/packages/agents/settlement/src/refund-processing/refund-engine.ts
index f856ac9..dff6afc 100644
--- a/packages/agents/settlement/src/refund-processing/refund-engine.ts
+++ b/packages/agents/settlement/src/refund-processing/refund-engine.ts
@@ -19,16 +19,21 @@
  *    Presence of a waiver code ≠ skip penalty.
  * See docs/knowledge-base/waiver-typology.md.
  *
+ * Partial refunds (issue #150 / KB partial-refund-residual-value.md):
+ * - Require `partial_valuation` with PUBLISHED_FARE or CARRIER_SPECIFIC
+ * - Passenger path = Cat 33 penalty + THB unused base/taxes
+ * - NEVER original−used, coupon-ratio, MPA-P, or haversine
+ *
  * // DOMAIN_QUESTION: per-carrier ATPCO Cat33 data ingestion pipeline.
  * // DOMAIN_QUESTION: DQ-W1 — map free-text waiver codes → WaiverEffect
  * //   (only when a waiver_code is present; not when Cat 33 data is absent).
  */
 
 import Decimal from 'decimal.js';
-import { AgentInputValidationError } from '@otaip/core';
+import { AgentInputValidationError, domainInputRequired } from '@otaip/core';
 import type {
   RefundProcessingInput,
-  RefundProcessingOutput,
+  RefundProcessingResult,
   RefundRecord,
   RefundAuditTrail,
   RefundPenaltyRule,
@@ -314,7 +319,7 @@ function resolveVoluntaryPenalty(
   return { baseFareRefund, penalty, forfeited: false };
 }
 
-export function processRefund(input: RefundProcessingInput): RefundProcessingOutput {
+export function processRefund(input: RefundProcessingInput): RefundProcessingResult {
   assertRefundWaiverInput(input);
 
   const originalBase = new Decimal(input.base_fare);
@@ -326,6 +331,8 @@ export function processRefund(input: RefundProcessingInput): RefundProcessingOut
   let taxBreakdown: TaxItem[];
   let penalty: Decimal;
   let couponsRefunded: number[];
+  let residualMethod: 'PUBLISHED_FARE' | 'CARRIER_SPECIFIC' | undefined;
+  let flownBaseFare: string | undefined;
 
   switch (input.refund_type) {
     case 'FULL': {
@@ -346,23 +353,45 @@ export function processRefund(input: RefundProcessingInput): RefundProcessingOut
     }
 
     case 'PARTIAL': {
-      const refundableCoupons = (input.coupons_to_refund ?? []).filter((c) => c.refundable);
-      const couponRatio =
-        input.total_coupons > 0
-          ? new Decimal(refundableCoupons.length).dividedBy(input.total_coupons)
-          : new Decimal(0);
+      const valuation = input.partial_valuation;
+      if (!valuation) {
+        return domainInputRequired({
+          missing: [
+            'partial_valuation',
+            'published_fare_or_carrier_residual_amounts',
+          ],
+          description:
+            'PARTIAL refund requires explicit PUBLISHED_FARE or CARRIER_SPECIFIC unused base/taxes. Rejected: original−used without method, coupon-count ratio, MPA-P interline proration, and haversine through-fare splits. Absence of Cat 33 data means free Cat 33 penalty once amounts are supplied — it does not invent a proration method. THB = IATA Ticketing Handbook (cite by name only).',
+          references: [
+            'docs/knowledge-base/partial-refund-residual-value.md',
+            'IATA Ticketing Handbook (THB) — cite by name only',
+            'GitHub issue #150',
+          ],
+        });
+      }
 
-      const proratedBase = originalBase.times(couponRatio).toDecimalPlaces(2);
-      const resolved = resolveVoluntaryPenalty(input, rule, proratedBase);
+      if (valuation.method !== 'PUBLISHED_FARE' && valuation.method !== 'CARRIER_SPECIFIC') {
+        return domainInputRequired({
+          missing: ['partial_valuation.method'],
+          description:
+            'partial_valuation.method must be PUBLISHED_FARE or CARRIER_SPECIFIC. MPA-P is airline interline settlement, not passenger residual.',
+          references: [
+            'docs/knowledge-base/partial-refund-residual-value.md',
+            'GitHub issue #150',
+          ],
+        });
+      }
+
+      const unusedBase = new Decimal(valuation.unused_base_fare);
+      const resolved = resolveVoluntaryPenalty(input, rule, unusedBase);
       baseFareRefund = resolved.baseFareRefund;
       penalty = resolved.penalty;
+      taxBreakdown = valuation.unused_taxes;
+      taxRefund = sumTaxes(taxBreakdown);
+      residualMethod = valuation.method;
+      flownBaseFare = valuation.flown_base_fare;
 
-      taxRefund = originalTax.times(couponRatio).toDecimalPlaces(2);
-      taxBreakdown = input.taxes.map((t) => ({
-        code: t.code,
-        amount: new Decimal(t.amount).times(couponRatio).toDecimalPlaces(2).toFixed(2),
-        currency: t.currency,
-      }));
+      const refundableCoupons = (input.coupons_to_refund ?? []).filter((c) => c.refundable);
       couponsRefunded = refundableCoupons.map((c) => c.coupon_number);
       break;
     }
@@ -402,6 +431,8 @@ export function processRefund(input: RefundProcessingInput): RefundProcessingOut
     tax_refunded: taxRefund.toFixed(2),
     commission_recalled: commissionRecalled.toFixed(2),
     coupons_refunded: couponsRefunded,
+    ...(residualMethod !== undefined ? { residual_method: residualMethod } : {}),
+    ...(flownBaseFare !== undefined ? { flown_base_fare: flownBaseFare } : {}),
   };
 
   // Settlement fields
diff --git a/packages/agents/settlement/src/refund-processing/types.ts b/packages/agents/settlement/src/refund-processing/types.ts
index a67b55e..9e20e23 100644
--- a/packages/agents/settlement/src/refund-processing/types.ts
+++ b/packages/agents/settlement/src/refund-processing/types.ts
@@ -7,8 +7,15 @@
  * Waiver typology: docs/knowledge-base/waiver-typology.md
  * - No Cat 33 data / no match → free refund (ATPCO default; not fail-closed).
  * - Bare waiver_code without waiver_effect → fail closed (≠ skip penalty).
+ *
+ * Partial refunds: Cat 33 + IATA Ticketing Handbook (THB) practice, with
+ * explicit PUBLISHED_FARE or CARRIER_SPECIFIC valuation — never
+ * original−used / coupon-ratio / MPA-P. See
+ * docs/knowledge-base/partial-refund-residual-value.md (issue #150).
  */
 
+import type { DomainInputRequired, PassengerPartialValuation } from '@otaip/core';
+
 export type RefundType = 'FULL' | 'PARTIAL' | 'TAX_ONLY';
 
 export type SettlementSystem = 'BSP' | 'ARC';
@@ -155,6 +162,10 @@ export interface RefundAuditTrail {
   commission_recalled: string;
   /** Coupons refunded */
   coupons_refunded: number[];
+  /** Residual valuation method for PARTIAL refunds */
+  residual_method?: 'PUBLISHED_FARE' | 'CARRIER_SPECIFIC';
+  /** Flown base fare when PUBLISHED_FARE valuation supplied */
+  flown_base_fare?: string;
 }
 
 export interface RefundRecord {
@@ -261,6 +272,11 @@ export interface RefundProcessingInput {
    * full refund). The engine never invents a penalty amount.
    */
   cat33_rules?: Cat33Rules;
+  /**
+   * Explicit passenger residual for PARTIAL refunds (PUBLISHED_FARE or
+   * CARRIER_SPECIFIC). Required for PARTIAL — no coupon-ratio fallback.
+   */
+  partial_valuation?: PassengerPartialValuation;
 }
 
 export interface RefundProcessingOutput {
@@ -271,3 +287,6 @@ export interface RefundProcessingOutput {
   /** Commission recalled (decimal string) */
   commission_recalled: string;
 }
+
+/** Successful refund or fail-closed domain sentinel. */
+export type RefundProcessingResult = RefundProcessingOutput | DomainInputRequired;
diff --git a/packages/core/src/domain/index.ts b/packages/core/src/domain/index.ts
index c6a9cc2..44f7c05 100644
--- a/packages/core/src/domain/index.ts
+++ b/packages/core/src/domain/index.ts
@@ -1,2 +1,11 @@
-export type { DomainInputRequired } from './types.js';
-export { domainInputRequired, isDomainInputRequired } from './types.js';
+export type {
+  DomainInputRequired,
+  PassengerResidualMethod,
+  PassengerPartialValuation,
+  RejectedPassengerResidualMethod,
+} from './types.js';
+export {
+  domainInputRequired,
+  isDomainInputRequired,
+  REJECTED_PASSENGER_RESIDUAL_METHODS,
+} from './types.js';
diff --git a/packages/core/src/domain/types.ts b/packages/core/src/domain/types.ts
index 721baf5..d61ec36 100644
--- a/packages/core/src/domain/types.ts
+++ b/packages/core/src/domain/types.ts
@@ -36,3 +36,54 @@ export function isDomainInputRequired(
     (value as { status?: unknown }).status === 'DOMAIN_INPUT_REQUIRED'
   );
 }
+
+/**
+ * Passenger residual / partial-refund valuation method (Agents 5.1 / 5.2 / 6.1).
+ *
+ * See `docs/knowledge-base/partial-refund-residual-value.md`.
+ *
+ * - FULLY_UNUSED — no flown coupons; residual/refundable base = ticketed base
+ * - PUBLISHED_FARE — caller-supplied unused/flown amounts from published fare
+ *   for flown sectors (Cat 33 + IATA Ticketing Handbook practice; not MPA-P)
+ * - CARRIER_SPECIFIC — carrier residual formula amounts supplied by caller
+ *
+ * Cat 33 absent / unmatched → free refund penalty (ATPCO public default) —
+ * that is separate from requiring an explicit valuation method on partials.
+ *
+ * MPA-P / TPM / haversine / coupon-ratio / original−used without method are
+ * explicitly rejected and must never appear as a successful method.
+ *
+ * Note: THB means the IATA Ticketing Handbook (cite by name only). Do not
+ * invent alternate expansions of the acronym.
+ */
+export type PassengerResidualMethod =
+  | 'FULLY_UNUSED'
+  | 'PUBLISHED_FARE'
+  | 'CARRIER_SPECIFIC';
+
+/** Methods that engines must refuse (issue #150). */
+export const REJECTED_PASSENGER_RESIDUAL_METHODS = [
+  'ORIGINAL_MINUS_USED',
+  'ORIGINAL_MINUS_CHANGE_FEE',
+  'MPA_P',
+  'HAVERSINE_THROUGH_FARE_SPLIT',
+  'COUPON_COUNT_RATIO',
+] as const;
+
+export type RejectedPassengerResidualMethod =
+  (typeof REJECTED_PASSENGER_RESIDUAL_METHODS)[number];
+
+/**
+ * Caller-supplied unused value after an explicit valuation method.
+ * Engines apply Cat 33 penalties to these amounts — they do not invent them.
+ * Cat 33 no-match still means penalty = 0 (free); missing method is fail-closed.
+ */
+export interface PassengerPartialValuation {
+  method: Exclude<PassengerResidualMethod, 'FULLY_UNUSED'>;
+  /** Unused base fare after published-fare / carrier valuation (decimal string). */
+  unused_base_fare: string;
+  /** Optional audit: flown base from that valuation. */
+  flown_base_fare?: string;
+  /** Unused taxes by code — required for partial money paths. */
+  unused_taxes: Array<{ code: string; amount: string; currency: string }>;
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 2788d3b..acf1634 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -52,8 +52,17 @@ export { fetchWithRetry, fetchOnce } from './http/index.js';
 export type { FetchOnceOptions } from './http/index.js';
 export type { FetchWithRetryOptions } from './http/index.js';
 
-export type { DomainInputRequired } from './domain/index.js';
-export { domainInputRequired, isDomainInputRequired } from './domain/index.js';
+export type {
+  DomainInputRequired,
+  PassengerResidualMethod,
+  PassengerPartialValuation,
+  RejectedPassengerResidualMethod,
+} from './domain/index.js';
+export {
+  domainInputRequired,
+  isDomainInputRequired,
+  REJECTED_PASSENGER_RESIDUAL_METHODS,
+} from './domain/index.js';
 
 export {
   EU261_BANDS,