fix: recognize corroborated empty Oracle associations

.project-docs/30-worklog/tasks/20261008-production-review-9e7b.md

@@ -21,10 +21,10 @@
 ## Outcome
 
 - Production direct reads now omit unsupported server sorting and use the platform's working GET `getProfiles` query. Original acquisition order, complete paging/recheck and response identity checks remain enforced. Legacy collection keeps its original sorting default.
-- Added source-field completion before deterministic processing: only candidate records' unresolved/invalid fields may be edited; optional absence requires an explicit decision. Original bytes are retained, revisioned decisions record the authenticated actor, and confirmation freezes a derived source. The same download request resumes from its saved acquisition without querying OHIP again. Existing price review, Finance validation, daily generation and monthly outbox behavior remain in use; XML processing is retained.
+- Added source-field completion before deterministic processing: only candidate records' unresolved/invalid fields may be edited. Normal optional block/package omission is now recognized under the narrow Oracle association policy described below; unresolved, failed or contradictory evidence still needs resolution. Original bytes are retained, revisioned staff decisions record the authenticated actor, and confirmation freezes a derived source. The same download request resumes from its saved acquisition without querying OHIP again. Existing price review, Finance validation, daily generation and monthly outbox behavior remain in use; XML processing is retained.
 - Browser recovery is scoped to this service/source context and user, preventing an old sandbox request from restoring into the production instance. Lost save/finalize responses, concurrent revisions and interrupted confirmation recover without a second processing intent.
 - Updated the existing local service at `http://127.0.0.1:8875/` to run this isolated checkout, retaining hotel57106, credentials, private database and output storage. Previous private launcher/config/plist were backed up before restart. No production deployment, remote push or integration into the unowned dirty primary checkout occurred.
-- Reused the complete, immutable real 2026-10-07 capture; verified all531 inventory files and both original hashes before importing into request `45e0e20ee75a46e098a0e32d650133a9`. Import made zero new Oracle calls. The live task is `needs_data_review`, no processing job exists, and it has26 unresolved fields across19 rows:1 room,18 block codes and7 package lists. No real business values were supplied or implicitly confirmed; no real daily/monthly was generated.
+- Reused the complete, immutable real 2026-10-07 capture; verified all531 capture files and both original hashes before importing into request `45e0e20ee75a46e098a0e32d650133a9`. Its initial26 source decisions were1 room,18 block codes and7 package lists. The optional-association follow-up below reinterpreted only corroborated normal omissions, preserving all original bytes and staff decisions. Current live review is revision1 with only1 unresolved required room; no processing job, staff confirmations or real daily/monthly exist. Import and reanalysis made zero new Oracle calls.
 
 ## Verification
 
@@ -38,7 +38,7 @@
 
 ## Follow-ups
 
-- Reconcile the API source selection with the original Oracle report before asking staff to resolve the26 currently presented field decisions. The later original-XML audit below proves that15 decisions concern reservations absent from the manual10/7 report and11 concern optional values explicitly blank in that report. Neither these source differences nor the original optional-field rules can be resolved by asking staff to invent values. Subsequent existing price review and real daily/monthly acceptance remain pending. No synthetic room, source confirmation, or status-based exclusion has been introduced.
+- The user explicitly deferred API/XML population alignment. That issue remains separate and must not block fixing normal optional omission or be represented as resolved by this change. The remaining10/7 room belongs to confirmation300007418, a Cancelled/unassigned source reservation; do not invent a room or silently exclude the reservation. Real report acceptance still requires resolving the actual remaining input and, when resumed by the user, the desired source selection/text mappings. Existing price review and real daily/monthly acceptance remain pending.
 - Integration owner should promote the accepted behavior and production compatibility evidence, then integrate this branch into the primary project. Keep this checkout while the local service runs from it. It is manually created, not eligible for automatic skill-managed retirement.
 - Production deployment/configuration and remote publishing are separate follow-ups. This turn only activated the local instance against the existing production read service.
 
@@ -46,7 +46,7 @@
 
 - Update canonical current-state/data-flow/success-criteria with the separate upstream source-field review and its boundary with the existing price-only processor/Finance review. Preserve ADR-006's original scope; decide whether an additional ADR is appropriate at integration.
 - Promote the four supported direct search parameters, GET profile lookup compatibility, service-context browser recovery and immutable original/manual decision audit into integration-owned documentation.
-- Record that real10/7 acquisition is complete but its daily/monthly acceptance awaits staff decisions. Avoid claiming successful report generation from synthetic regression evidence.
+- Record that real10/7 acquisition is complete and normal optional omission is resolved under a constrained source policy; daily/monthly acceptance still awaits the remaining input and separately deferred source selection. Avoid claiming successful report generation from synthetic regression evidence.
 
 ## Concurrent Task Gate
 
@@ -125,3 +125,16 @@ Read: memory-index, project-positioning, current-state latest September sections
 - Public CLI0.5.0 catalog inspection succeeds against the existing Edge service, version0.12.0: searchHotelReservations remains a synchronous POST with an optional OracleDocument body and no typed mapping to res_detail report criteria. Only public metadata was requested; no credentials, grants, environment routing or hotel business data were read or changed. Private evidence: `production-validation-20261007/search-reservations-public-contract-20261008.json`.
 - Official documentation does not establish the current hotel's historical report status defaults. Oracle's [legacy RES_DETAIL parameters](https://docs.oracle.com/cd/E98457_01/opera_5_6_core_help/res_detail_help.htm) distinguish arrival/stay dates and include options from Reservations=All. Its Checked-In Today option refers to the current business date; this is not proof that a historical Cloud report excludes every InHouse reservation or includes only CheckedOut. The current [Oracle reservation API schema](https://raw.githubusercontent.com/oracle/hospitality-api-docs/main/rest-api-specs/property/v1/rsv.json) independently exposes actualArrivals, expectedArrivals and reservationStatuses, without defining their equivalence to res_detail. An independent read-only official-document audit reached the same limit; current Cloud report summaries do not supply the missing per-hotel saved parameter values.
 - Outcome: the user-confirmed two-day range explains the extra10/8 XML group only. Request the actual Oracle export parameter page, especially the date-type and Include selections, before choosing API inclusion criteria. Do not ask for the date again, infer status answers, or introduce CheckedOut-only filtering from this one sample. No code, source data, review decisions or service configuration changed, and no actual daily/monthly was generated. Public metadata/documentation reads required no business query or tests; Git whitespace and task documentation boundary checks apply to this documentation-only continuation.
+
+## Same-task Follow-up: Optional Information Versus Mandatory Anomalies
+
+- User explicitly defers API/XML reservation-population alignment and asks to resolve the earlier explanation of26 pending fields:25 optional-source confirmations versus1 original mandatory room error. Subsequent “继续” authorizes checking omission semantics and correcting the related product behavior. Do not resume status/date-scope changes as a prerequisite for this narrower work.
+- Concurrent gate Passed: resumed the same task, ownercodex, feature mode, branchcodex/arr-production-review, existing absolute worktree and base unchanged; no other owners. Existing planning context/ADR-004/006/007 and prior rule/history audits remain applicable; the user's production-read and multiple-agent consent supersede older September restrictions. Primary checkout's unknown changes remain untouched.
+- Project Context Loaded / Planning gate Passed: direct JSON and XML retain shared deterministic business rules; optional fields may legitimately be blank, required room values cannot be fabricated, original capture/manual decisions remain immutable and auditable. Scope is integrations/ohip optional observations and source-review page explanation/tests. Public contract reads and saved production capture may establish omission behavior; optional schema presence alone must not be claimed as proof that a failed/ambiguous read is empty. No new hotel business read is needed for the initial investigation.
+- Plan: independently review official/request contracts and existing capture completeness; distinguish proven empty observations from failed/ambiguous/unestablished values without inventing data. Correct the page's explanation of mandatory versus optional unresolved information and acquisition failure; add meaningful regression for affected branches. Activate verified local changes only after checking task activity and preserve actual staff decisions. Report the actual remaining confirmation count honestly, without promising automatic blank handling if contractual evidence is insufficient.
+- Research outcome: Oracle's official HTNG mapping directly identifies `getReservation` as the operation for booked packages; requested-element semantics and optional block/package models, combined with successful corroborated search/detail responses, support a narrow normal-omission policy. This is a reasoned conditional implementation, not a claim that Oracle explicitly guarantees all omitted structures are empty. The question to the platform colleague is withdrawn; no colleague determination or new grant/key is needed. Evidence and precise conditions are recorded in `50-evidence/topics/20261008-production-review-9e7b__oracle-optional-associations.md`.
+- Implementation outcome: fixed policy `oracle-optional-association/v1` resolves normal empty block/package associations and retains missing evidence, failed reads, malformed structures and contradictions. Source-review UI now distinguishes original mandatory/optional rules from fetch failure, conflict and invalid format. The original processor/validator/XML and date/status population are unchanged.
+- Existing-review outcome: added internal fixed-projection reanalysis, no public route. Original acquisition bytes/manifest/checkpoints and all manual decisions remain immutable/preserved; reanalysis is separately hash-pinned and revisioned, not recorded as staff confirmation. Final audit binds original/reanalysis sources and receipts; finalization remains explicit, with concurrency/idempotency/tamper/interrupted-publication tests.
+- Verification:88 Python tests passed with disposable real local PostgreSQL enabled, no skips (33 source-review/executor/database and55 source acquisition tests);44 JavaScript tests passed. Independent policy review caught malformed indicator-name and contradictory empty-block edge cases, both fixed and retested. Offline real replay verified531 original files and all176 recorded HTTP requests with zero network calls, preserving58 rows, every other source/field/context/related value and order.36 full-source block observations and16 package observations became empty, resolving25 candidate decisions.
+- Local activation and observed result: dry-run on a private copy reduced26 decisions to1 without manual decisions or finalization. Verified no active queued/downloading/processing task before service stop; backed up review and executor checkpoint to private `source-reanalysis-backup-20261008-105211`, applied the same checked reanalysis, then restarted the existing service. Authenticated API and CUA both show10/7 revision1,0/1 confirmed, only required room for300007418, `can_finalize=false`, no job/daily/monthly. Page retained as deliverable with10/7 selected; XML upload and separate9/17 pending entry remain. The existing9/17 capture/review was not reinterpreted or queried. Screenshot and full replay receipts remain private outside Git.
+- Follow-up/promotion candidate: promote the documented limited optional-association semantics and product explanations at integration. Remaining10/7 room is not fabricated; its cancelled/unassigned report inclusion remains a separately deferred business-scope question. Real daily/monthly acceptance, primary-checkout integration and remote deployment are not claimed by this task.

.project-docs/50-evidence/topics/20261008-production-review-9e7b__oracle-optional-associations.md

@@ -0,0 +1,46 @@
+# Oracle optional reservation associations
+
+## Question and scope
+
+The user asked why10/7 showed26 manual field decisions when XML rules allow empty block and package fields, and instructed Codex to research Oracle directly after the platform colleague could not establish the return semantics. The user expressly deferred comparing API and XML reservation populations. This record does not establish report-selection equivalence or authorize status filtering.
+
+## Official evidence
+
+- Oracle's [HTNG migration mapping](https://docs.oracle.com/en/industries/hospitality/integration-platform/ohipu/c_htng.htm) maps Retrieve Booked Packages / FetchBookedPackages to `getReservation`, while configuration package details use a different operation.
+- The official [RSV schema](https://github.com/oracle/hospitality-api-docs/blob/main/rest-api-specs/property/v1/rsv.json) describes cumulative `fetchInstructions`. The current application explicitly requests `Packages`, `Reservation`, `DailySummary` and the other existing elements; `reservationPackages` and block-association structures are optional.
+- Oracle's [24.1 property API release notes](https://docs.oracle.com/en/industries/hospitality/opera-cloud/24.1/oprnc/c_feature_summary.htm) describe `reservationBlock` information returned for reservations associated with a block.
+- Public Edge catalog0.12.0 shows `getPackage` requires a known `productCode`; it cannot discover an unknown attached-package list. `getReservationsByPackage` is a consumption-date query, not an equivalent full single-reservation package-list retrieval. No permission or credential change is needed.
+
+These sources establish operation purpose, requested-element semantics and optional association models. They do not contain a universal literal guarantee that every absent field means none. The implementation is a conditional contract interpretation supported by those semantics and corroborating successful captured responses; failed, ambiguous or malformed reads are not converted to empty.
+
+## Narrow policy: oracle-optional-association/v1
+
+- Omitted packages may become empty only after successful, validated reservation detail requested with `Packages`, with an explicit valid search indicator list. Every indicator has a nonempty string name; `PACKAGEITEM` must be absent or occur once with a legal integer zero. Positive, missing, negative, boolean or duplicate package counts remain unresolved; a positive count also contradicts explicit `[]`.
+- Omitted block association may become empty only when search and arrival-day detail both omit it, with no additional detail-level block structure. Single-sided omission, explicit null/invalid structures and code/identity disagreement remain unresolved. Existing explicit empty-ID handling also checks all available layers for structure, hotel and nonempty block-name contradictions.
+- An identified block's failed supplementary read stays failed. Other optional fields receive no blanket omission rule. Original whitelist, required-field validation, room/date deduplication, pricing and XML logic are unchanged.
+- UI descriptions separately identify original required/optional rules, read failure, conflicting information and invalid format.
+
+## Saved10/7 evidence and safe replay
+
+Original complete capture:58 ordered rows,176 successful HTTP responses,531 files including manifest.42 detail rows have nonempty package arrays and positive `PACKAGEITEM`;16 omit packages with valid lists and no package indicator.22 search/day pairs contain block associations;36 omit both. No positive package indicator accompanies missing packages.
+
+Original capture manifest SHA256: `bcfeb6390fc553754b917f9c935a532916e6bd10d4e95ee43450895e760cd9fc`.
+Original ARR data SHA256: `805799ba2f3edd7f1cf18c14e5304908061d6194a241c5fc255192728b7f388a`.
+
+Offline-only recorded transport verified every original file hash/size, matched all176 method/path/body requests, replayed exact response bytes, and made zero network calls. New private capture changed only36 missing block observations and16 missing package observations to empty, plus the named policy tag; all other fields, record order, context, source references and related facts were strictly equal. These52 source observations include25 manual candidate decisions (18 block,7 package); noncandidate rows need no manual decisions. Two remaining company gaps are outside the original rate whitelist; only the original required-room issue remains in review.
+
+Reanalysis manifest SHA256: `d39177c5aad3c5b235c04aab8693fca51580c15f6b5210aa2d4871276d8e3507`.
+Reanalysis ARR data SHA256: `2abbebb36a86f701722677ce103e4b3e02fffeb0c369bacd0e0c3bbbb9e9246f`.
+Private evidence directory: `/Users/chillishark/Library/Application Support/ARR2.0/production-validation-20261007/optional-association-reanalysis-e89e46a9e65c`.
+
+## Existing review preservation and result
+
+Internal maintenance only, no new HTTP route: `DataFieldReviews.apply_source_reanalysis` accepts the fixed policy and exact missing-reason-to-empty projection, preserving original acquisition/checkpoint hashes and all staff decisions. Reinterpretation bytes and receipt are immutable and hash-referenced; a separate revisioned `source_reanalysis` event is recorded without fabricating staff confirmations. Manual decisions always take priority. Finalization remains explicit and frozen reports include both original and reanalysis evidence. Stale/concurrent updates, unrelated value edits, tampering and changes after finalization are rejected; same evidence retries are idempotent and interrupted publication recovers.
+
+After dry-run validation on a private copy and confirming zero active queue tasks, the existing local service was stopped, original review/executor checkpoint backed up,10/7 reanalysis applied and the same service restarted. Local authenticated reads and CUA page inspection show revision1,0/1 confirmed, only `DISP_ROOM_NO` for confirmation300007418, disabled generation, no job and both10/7 and9/17 pending entries. The unrelated existing9/17 review is unchanged; historical pending captures are not silently rewritten by changing future acquisition code. No real daily/monthly was generated.
+
+Verification:88 targeted Python tests passed with real disposable local PostgreSQL and no skips;44 JavaScript tests passed; syntax/whitespace checks passed. Independent source-policy review found two edge cases (malformed indicator name and contradictory explicit empty block association); both were fixed with regression tests and independently rechecked. Screenshot in the private evidence directory: `local-review-after-reanalysis.png`.
+
+## Promotion candidate
+
+Integration owner should promote the conditional optional-association policy and required/optional/failure distinction to canonical source-contract/product documentation, with this evidence and its limits. Preserve the separate unresolved cancelled/unassigned reservation selection question and do not claim a successful real daily/monthly or exact XML equivalence. No policy reversal or new human approval is required for normal optional blanks already allowed by the original business rules.