# Error Contract

## Atomic invocation

Treat one XML invocation as an atomic file-processing unit.

On any input, XML, price, routing, write, structured-completeness, or independent-validation error:

- do not return a formal daily workbook;
- delete candidate daily/structured files from the failed attempt;
- keep the source XML unchanged;
- write `异常清单.xlsx`;
- write failed `result.json` when its requested path is valid;
- write failed `structured-result.json` when its requested path is valid;
- set `activation_eligible: false`.

The failed structured payload still preserves every parsed reservation and its final outcome. It never references a daily artifact.

## Exit codes

| Exit | Meaning |
|---:|---|
| `0` | Processing and independent validation succeeded |
| `2` | Business-data failure |
| `3` | Invocation/input-contract failure |
| `4` | Unexpected dependency/internal failure |

## Exception workbook

Columns:

`ERROR_CODE`, `STAGE`, `SOURCE_LOCATION`, `COMPANY_NAME`, `RATE_CODE`, `EFFECTIVE_RATE_AMOUNT`, `CONFIRMATION_NO`, `MESSAGE`.

Write one row per independently actionable error. Leave unavailable fields blank.

## Stable error families

- `INPUT_*`: path, extension, output isolation, unsafe declaration, or invocation error.
- `XML_*`: parse/root/structure/date/required-field/value error. Zero nights are valid; negative nights use `XML_NEGATIVE_NIGHTS`.
- `PRICE_*`: price table, ambiguity, duplicate normalized key, or unmatched candidate.
- `ROUTING_*`: ambiguous or unusable deterministic `channel_key`.
- `OUTPUT_*`: missing/malformed output, wrong header/type/value/order/hash/filename, formula, duplicate, or independent replay mismatch.
- `STRUCTURED_*` / `OUTPUT_STRUCTURED_*`: invalid path-free artifact, outcome reconciliation, derived key, channel fact, or record payload.
- `INTERNAL_ERROR`: concise unexpected failure without secrets.

## Success/failure invariants

- `status` is `success` or `failed`.
- Output references in `result.json` are basenames, never paths.
- Success lists daily and structured files, lists no exception file, and has no errors.
- Failure lists no daily file, lists an exception file, and has at least one error.
- `metrics.channels` is a deterministic array of `{ "worksheet": string, "rows": integer }`.
- Structured success requires exact artifact metadata, balanced five-outcome counts, no `validation_failed`/`price_unmatched`, and `activation_eligible: true`.
- Structured failure has `output_rows = 0`, no channel metrics, no daily artifact, a non-empty error array, and `activation_eligible: false`.
- Never place guest details in the public `message`.

## Database boundary

This Skill never executes database DDL or DML. ARR may start its transaction only after process exit `0`, Schema validation, and independent re-hashing. ARR activates a new same-day version only as the last step of a successful transaction; any failure must roll back and leave the previous current version unchanged.