From f72d471a3178f24059cb6be0dd1aca96aab026c5 Mon Sep 17 00:00:00 2001 From: Erik Date: Sat, 5 Sep 2026 20:12:31 +0200 Subject: [PATCH] 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 --- .../c1a-building-bridge-repair-contract.md | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 docs/research/2026-09-01-overhaul/c1a-building-bridge-repair-contract.md diff --git a/docs/research/2026-09-01-overhaul/c1a-building-bridge-repair-contract.md b/docs/research/2026-09-01-overhaul/c1a-building-bridge-repair-contract.md new file mode 100644 index 00000000..8ffb6100 --- /dev/null +++ b/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.