feat: prepare ARR for controlled public deployment

arr-opera-daily-ingest/references/error-contract.md

@@ -0,0 +1,59 @@
+# 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.