docs(overhaul): bound retail part-array building bridge repair

Port the proven missing box admission and immediate destination transit, preserving sphere callers and separate registered source/equality residuals. Keep the failed authored-input diagnostic and original golden untouched.

Co-Authored-By: OpenAI Codex <noreply@openai.com>

docs/research/2026-09-01-overhaul/c1a-building-bridge-repair-contract.md

@@ -0,0 +1,136 @@
+# C1a / AP-159 — distinct part-array building bridge
+
+Lead bounded production contract,2026-09-05. Base846cdd94b on the campaign
+branch. This follows accepted bounded evidence, not a third diagnostic fix.
+The failed diagnostic and original scratch witness remain unchanged.
+
+## Evidence and objective
+
+Read `c1a-bridge-native-contract.md`,
+`c1a-authored-input-diagnostic-verification.md`, the worldbuilder inventory,
+and the current methods below before implementing. The full raw capture is
+in preserved s5-c1a-geometry's r3 artifact directory. Lead and independent
+read-only review agree on the first missed predicate: the four outdoor0009
+building routes into0114 must reject the ramp at destination containment
+node0. The current sphere helper admits it. Direct paired retail membership
+is0112/0113/0009,21 entries, not production's extra0114/28 entries.
+
+Port only the distinct part-array bridge and its immediate destination
+transit. Preserve ordinary sphere/player behavior, seed/residency policy,
+existing indoor traversal, shared box/plane primitives and registry ownership.
+No scene-ID condition, shader/depth/visibility mask, package change, drawing-
+sphere source repair, scaling change, epsilon tie correction, FPS work, or
+known retail cathedral leakage fix belongs here.
+
+## Ownership and files
+
+Implement directly in campaign worktree peaceful-blackburn-5333f0; do not
+reuse or modify the preserved s5-c1a-geometry witness. Implementation agent
+may edit only:
+
+- `src/AcDream.Core/Physics/CellTransit.cs` — new focused private/internal
+  part-array building helper, its one call site and directly stale comments.
+- `tests/AcDream.Core.Tests/Physics/CellTransitBuildingPartsTests.cs` — new
+  focused synthetic production-entry tests and local fixtures.
+
+Lead owns register/architecture/ledger, integration, full tests, final
+installed-DAT witness and graphical gates. Do not commit, create agents,
+modify existing tests/expected values, or launch clients. Return source and
+artifact hashes with exact build/test outcomes.
+
+## Native contract to implement
+
+Named CSortCell00534080→CBuildingObj006B52A0→CEnvCell0052C680, not sphere
+0052C5D0. Paired exe SHA006FFEADC5D679C871497112A5BD1F87714D0E273E2166BAE5052DDE369297B1.
+Call006B52E5 targets0052C680. Native note seals the predicates and bytes.
+
+1. Only `BuildShadowCellSetFromParts`' outdoor building branch changes.
+   It passes the existing matching ordered boxes and spheres, candidates,
+   outside-expansion context/latch into the new helper. No fresh shape owner
+   or second traversal engine. Existing sphere-count/empty guards stay.
+2. For each authored building portal in original order, resolve the loaded
+   destination only (GetVisible semantics, no load hint/request); negative
+   signed reciprocal index is skipped. A missing/rootless destination keeps
+   existing unavailable-content policy. Resolve the reciprocal portal's
+   plane through the current graph/prepared `TryGetPortalPlane` seam; use
+   the reciprocal portal side, not the building portal flags.
+3. Walk matching parts in original order. Transform the supplied sphere
+   center into destination local space, radius+FEpsilon. Raw side1 accepts
+   d<=+pad; raw side0 accepts d>=-pad. These inclusive BUILDING comparisons
+   are deliberately opposite the indoor exit gate. Keep the currently
+   registered strict indoor equality residual unchanged.
+4. Refit the supplied authored part box through destination inverse frame.
+   Admit the portal-plane test only when classification is CROSSING or SAME
+   reciprocal side. Use managed Straddle, not native numeric3 cast into the
+   managed enum. Then require existing `CollisionTraversal.BoxIntersectsCell`.
+   Do not replace that with sphere/point containment or new BSP math.
+5. On first complete part hit, append destination, then immediately invoke
+   its existing `FindTransitCellsBox` with the COMPLETE ordered part array,
+   before the next building portal. Propagate its exterior request through
+   the SAME outside latch/`AddAllOutsideCellsFromParts` context. This immediate
+   call is mandatory EVEN IF CellArray.Add suppressed an existing destination
+   ID. The outer growing-array walk remains, and no second visited set or
+   recursion through building bridges is introduced. Break only the current
+   portal's part loop, then continue the next authored building portal.
+
+Keep ordinary `CheckBuildingTransit` overloads byte-for-byte unchanged except
+unavoidable directly stale documentation; their sphere-only behavior and
+hitsInteriorCell reporting are correct for their own callers.
+Do not silently invent policy for malformed positive reciprocal indices;
+identify existing validation/error handling if this requires a new choice.
+
+## Required discriminating tests
+
+Drive real `BuildShadowCellSetFromParts` where possible; tests may use a
+focused internal helper only where necessary to observe duplicate/immediate
+ordering. Reuse current cache/flat fixture conventions. New containment
+fixtures should use explicit planes and null positive-child terminals, not
+an unproven native leaf-plane shortcut. Test expectations are literals, not
+computed by the helper under test.
+
+- Sphere hits destination but authored box misses it: building route rejects;
+  ordinary sphere helper on the same fixture still admits. Include a
+  cathedral-like horizontal plane with maxZ below it by more than epsilon.
+- Both reciprocal sides and CROSSING-or-SAME box admission; opposite-side
+  rejection. Two exact cheap equality cases reach box admission, with an
+  adjacent representable value beyond each boundary rejected.
+- Earlier part rejects, later part admits; no truncation to part0. A first
+  hit breaks the part loop and preserves building portal order.
+- Negative reciprocal, unavailable/rootless destination, empty parts, and
+  unloaded active/outdoor candidates retain existing behavior without loads.
+- Ordered destination expansion: building portal to A, A admits C, then
+  building portal to B gives A,C,B (not A,B,C) in the relevant suffix. Cover
+  duplicate destination handling without suppressing its immediate transit;
+  ensure the shared outside latch remains coherent.
+- Prepared-flat topology plane resolution, including polygon ID distinct
+  from its array index; do not rely only on graph-only test fixtures.
+- Existing ordinary sphere, indoor box, and registration tests remain green.
+
+First run the new tests against the original production call to establish
+their expected failures. Then implement and run them green. If practical,
+perform one bounded immediate-expansion mutation after the correct patch
+to prove the ordering test fails; restore only the exact owned lines via
+apply_patch, rehash restored source, and rerun narrow tests. No git reset,
+checkout, clean or stash, and no uncontrolled mutation/retry loop.
+
+## Execution and return boundary
+
+Check both client names/debugger absent and ACE UDP9000 before ANY build/test.
+One build/test process at a time. Release only; fresh artifacts under
+`artifacts/s5-c1a-building-parts-20260905-r1/`, separate pre-fix/final logs/TRX.
+Allowed affected lane: new tests plus existing CellTransitCheckBuildingTransit,
+CellTransitFindTransitCellsBox, BuildShadowCellSet tests, excluding opt-in
+external/timing/manual lanes by the repository's normal hermetic policy.
+No broad solution run or graphical launch by the implementer.
+
+Return the small code delta, exact first pre-fix failures, test counts/exit
+codes, any mutation failure/restoration hashes, and identified residuals.
+Independent review is limited to native bridge/ordering and production
+ownership/coverage. A code finding receives a bounded fix round; a third
+fix round stops and is written up. No fourth diagnostic repair or golden
+relaxation may be hidden inside this production contract.
+
+Before landing, lead narrows only AP159's building-bridge clause; AD117's
+non-physics sphere substitution and the two independent boundary ties remain.
+The implementation cannot claim overall C1a/G4 pass before real installed
+membership/determinism, full Release and final graphical gates. No main merge.