feat: add daily manual price review workflow

arr-opera-daily-ingest/references/structured-output.md

@@ -2,17 +2,17 @@
 
 ## Purpose
 
-`structured-result.json` version `3.0` is the daily fact payload consumed by the trusted ARR adapter. It contains every XML source reservation, including filtered, duplicate, invalid, and unmatched rows.
+`structured-result.json` version `4.0` is the daily fact/review payload consumed by the trusted ARR adapter. It contains every XML source reservation, including filtered, duplicate, invalid, candidate and unmatched rows. Historical v3 artifacts remain ARR read-compatible only; they do not gain manual-review behavior.
 
-`result.json` is the Agent/front-end run result. Do not add database records to it. Do not reconstruct database rows from the XLSX.
+`result.json` is the ARR/front-end run result. Do not add database records to it. Do not reconstruct database rows from the XLSX.
 
 ## Transport boundary
 
-- `fetch_oss_file` and its OSS credentials belong to the Agent runtime, not this Skill.
-- The Agent passes the fetched local XML path into the processor.
+- Object storage materialization and its credentials belong to the ARR runtime, not this Skill.
+- The runtime passes one already-fetched local XML path into the processor.
 - ARR already knows the job/source-file identity from the upload context and binds that identity to this payload after comparing the XML hash.
 - Structured artifact objects contain no local absolute path, OSS key, signed URL, AccessKey, or database credential.
-- Agent-local paths are ephemeral orchestration data and must not be persisted as business facts.
+- Runtime-local paths are ephemeral orchestration data and must not be persisted as business facts.
 
 ## Batch fields
 
@@ -25,8 +25,10 @@ The payload includes:
 - `source_rows`
 - `removed_by_rate_code`
 - `removed_as_duplicates`
-- `output_rows`
-- five-outcome reconciliation
+- `output_rows`, `candidate_rows`, `review_required_rows`, and `review_issue_count`
+- six-outcome reconciliation
+- grouped, privacy-minimized `review_issues` with fixed-table candidate-price comparisons
+- `review_case_id`, `manual_override_sha256`, and `manually_priced_rows` on final manual replay only
 - channel counts
 - path-free XML/daily/result/exception artifact metadata
 - every XML source record in original order
@@ -41,12 +43,13 @@ The structured file does not hash itself, avoiding self-hash recursion.
 Allowed outcomes:
 
 - `retained`
+- `candidate`
 - `excluded_rate_code`
 - `duplicate`
 - `validation_failed`
 - `price_unmatched`
 
-Duplicates point to an earlier `source_sequence`. `decision_codes` explain deterministic choices.
+Duplicates point to an earlier `source_sequence`. `decision_codes` explain deterministic choices. A final replay changes only approved missing-key rows to `retained` with `pricing_method: manual_review` and `MANUAL_PRICE_APPLIED`; candidate rows never enter Finance facts.
 
 For direct XML:
 
@@ -77,6 +80,6 @@ It may then expose `booking.booking_source_rows.hotel_raw` as the original booki
 
 ## Activation boundary
 
-`activation_eligible: true` means only that the deterministic file pipeline passed. It does not mean database commit succeeded.
+`activation_eligible: true` means only that the deterministic final file pipeline passed. It does not mean database commit succeeded. `review_required` is false and has no daily/report artifact.
 
-ARR must revalidate the Schema and hashes, write file/version/record/channel/lookup rows in one transaction, and switch the current daily version last. A rerun of the same business date creates a new immutable version; only the successful committed version becomes current.
+ARR must revalidate Schema, hashes and the independent replay before it writes file/version/record/channel/lookup rows in one transaction and switches the current daily version last. Review receipt writes only a case/items/events audit record. A frozen manual replay creates the first Finance version and one commit event only after that final validation succeeds.