fix(domain): fail-closed passenger residual via Cat 33 + THB (#150)

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).

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. |

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

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'`