From 2e861b15f24038b25a86a6875f8bf5738b65b132 Mon Sep 17 00:00:00 2001 From: RicheyWorks <730richey730@gmail.com> Date: Tue, 26 May 2026 03:42:19 -0700 Subject: [PATCH 1/2] Core-LB-G14: Add cloud shim boundary guard --- .../CORE_LOADBALANCER_FEATURE_CONTRACT.md | 21 ++++ ...alancerCloudBoundaryDocumentationTest.java | 97 +++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 src/test/java/com/richmond423/loadbalancerpro/docs/AgentCoreLoadBalancerCloudBoundaryDocumentationTest.java diff --git a/docs/agent/CORE_LOADBALANCER_FEATURE_CONTRACT.md b/docs/agent/CORE_LOADBALANCER_FEATURE_CONTRACT.md index a7b0d948..54868fa8 100644 --- a/docs/agent/CORE_LOADBALANCER_FEATURE_CONTRACT.md +++ b/docs/agent/CORE_LOADBALANCER_FEATURE_CONTRACT.md @@ -27,6 +27,20 @@ The first slot does not change runtime behavior. It records what the current cod - `RoutingStrategyRegistry`: request-level strategy lookup and default registration order. - Request-level routing strategies: `TailLatencyPowerOfTwoStrategy`, `WeightedLeastLoadStrategy`, `WeightedLeastConnectionsRoutingStrategy`, `WeightedRoundRobinRoutingStrategy`, and `RoundRobinRoutingStrategy`. +## Cloud Shim Boundary + +The core `LoadBalancer.initializeCloud(...)` method is a guarded API surface for optional cloud integration setup. The core feature contract treats this as a compatibility boundary, not as live-cloud validation, real-tenant validation, production cloud readiness, or credential-handling proof. + +Cloud manager access remains optional/nullable compatibility through the legacy nullable accessor plus `getCloudManagerOptional()` and `hasCloudManager()`. Core LoadBalancer contract evidence may verify that the shim remains bounded, documented, and guarded; it does not exercise real cloud accounts, introduce real credentials, mutate live infrastructure, or prove provider behavior. + +Reviewer-facing cloud boundary evidence must keep these claims explicit: + +- `initializeCloud(...)` input validation is part of the local guarded surface. +- `CloudManager` access is optional and may be absent. +- No Core-LB slot proves live-cloud validation. +- No Core-LB slot proves real-tenant validation. +- No Core-LB slot adds production cloud readiness, secrets, or credential material. + ## Strategy Invariants | Strategy or path | Current invariant to preserve | Current evidence | Follow-up hardening need | @@ -207,6 +221,7 @@ Use this map after Core-LB-G08 is merged/main-green to navigate the completed lo | Core-LB-G11 | Does weighted distribution preserve proportional, zero-weight, all-zero fallback, invalid-weight, and non-negative allocation invariants? | `CoreLoadBalancerWeightedDistributionInvariantTest` | Local deterministic weighted facade evidence only. | | Core-LB-G12 | Does consistent hashing remain deterministic and safe across fixed inputs, invalid key counts, no-candidate inputs, removal, replacement, and zero-load inputs? | `CoreLoadBalancerConsistentHashingInvariantTest` | Local deterministic hash-ring facade evidence only. | | Core-LB-G13 | Does accumulated allocation state rebalance safely across empty, round-robin, least-loaded, removal, replacement, capacity-aware, and predictive paths? | `CoreLoadBalancerRebalanceInvariantTest` | Local deterministic rebalance evidence only. | +| Core-LB-G14 | Are cloud-facing shim boundaries documented without implying live-cloud, real-tenant, credential, or production-readiness proof? | `AgentCoreLoadBalancerCloudBoundaryDocumentationTest` | Documentation guard only. | The reviewer trust map links back to this contract so reviewers can start from a single navigation surface and then drill into the focused tests above. @@ -284,6 +299,12 @@ Core-LB-G10 is tracked in [`CORE_LOADBALANCER_EVIDENCE_CONSOLIDATION.md`](CORE_L - Decision: current rebalance behavior redistributes accumulated allocated load through the selected facade strategy, keeps unallocated load out of accumulated state, and remains deterministic after removal or replacement cleanup. - Exit criteria: `CoreLoadBalancerRebalanceInvariantTest` protects accumulated-load rebalance behavior without changing production behavior. +### Core-LB-G14 - Cloud shim boundary audit + +- Scope: document and guard the `initializeCloud(...)`, optional cloud manager, and cloud shim compatibility boundaries. +- Decision: Core LoadBalancer cloud boundary evidence remains documentation/test-only and does not prove live-cloud validation, real-tenant validation, cloud production readiness, or credential handling beyond local guarded API-surface documentation. +- Exit criteria: `AgentCoreLoadBalancerCloudBoundaryDocumentationTest` protects cloud boundary wording and overclaim exclusions without changing production behavior. + ## Not-Proven Boundaries This contract and its guard do not prove: diff --git a/src/test/java/com/richmond423/loadbalancerpro/docs/AgentCoreLoadBalancerCloudBoundaryDocumentationTest.java b/src/test/java/com/richmond423/loadbalancerpro/docs/AgentCoreLoadBalancerCloudBoundaryDocumentationTest.java new file mode 100644 index 00000000..968461a9 --- /dev/null +++ b/src/test/java/com/richmond423/loadbalancerpro/docs/AgentCoreLoadBalancerCloudBoundaryDocumentationTest.java @@ -0,0 +1,97 @@ +package com.richmond423.loadbalancerpro.docs; + +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; +import java.util.Locale; +import java.util.regex.Pattern; + +import org.junit.jupiter.api.Test; + +class AgentCoreLoadBalancerCloudBoundaryDocumentationTest { + private static final Path CONTRACT = Path.of("docs/agent/CORE_LOADBALANCER_FEATURE_CONTRACT.md"); + private static final Path SOURCE = Path.of( + "src/test/java/com/richmond423/loadbalancerpro/docs/" + + "AgentCoreLoadBalancerCloudBoundaryDocumentationTest.java"); + private static final Pattern CREDENTIAL_ASSIGNMENT = Pattern.compile( + "(?i)(access[-_ ]?key|secret[-_ ]?key|token|password)\\s*[:=]\\s*[^\\s`\"']+"); + + @Test + void contractDocumentsCloudShimBoundaryWithoutAddingCloudProof() throws IOException { + String contract = read(CONTRACT); + String normalized = contract.toLowerCase(Locale.ROOT); + + for (String expected : List.of( + "cloud shim boundary", + "loadbalancer.initializecloud", + "guarded api surface", + "optional/nullable compatibility", + "getcloudmanageroptional()", + "hascloudmanager()", + "documentation/test-only")) { + assertTrue(normalized.contains(expected), "cloud boundary docs should include " + expected); + } + } + + @Test + void contractPreservesCloudNotProvenBoundaries() throws IOException { + String normalized = read(CONTRACT).toLowerCase(Locale.ROOT); + + for (String boundary : List.of( + "no core-lb slot proves live-cloud validation", + "no core-lb slot proves real-tenant validation", + "no core-lb slot adds production cloud readiness", + "no live-cloud validation", + "no real-tenant validation", + "no production readiness", + "no production certification")) { + assertTrue(normalized.contains(boundary), "missing cloud boundary " + boundary); + } + } + + @Test + void contractDoesNotIntroduceCloudOrCredentialOverclaims() throws IOException { + String normalized = read(CONTRACT).toLowerCase(Locale.ROOT); + + for (String forbidden : List.of( + "live-cloud validated", + "real tenant validated", + "cloud production ready", + "production cloud ready", + "certified cloud", + "benchmark proven")) { + assertFalse(normalized.contains(forbidden), "contract must not overclaim: " + forbidden); + } + + assertFalse(CREDENTIAL_ASSIGNMENT.matcher(read(CONTRACT)).find(), + "cloud boundary docs must not contain credential-looking assignments"); + } + + @Test + void guardTestOnlyReadsTrackedFiles() throws IOException { + String source = read(SOURCE); + + for (String forbidden : List.of( + "Files." + "write", + "Files." + "create", + "Files." + "delete", + "Process" + "Builder", + "Runtime." + "getRuntime", + ".ex" + "ec(", + "Http" + "Client", + "URL" + "Connection", + "Socket" + "(")) { + assertFalse(source.contains(forbidden), "guard test must not use " + forbidden); + } + } + + private static String read(Path path) throws IOException { + assertTrue(Files.exists(path), path + " should exist"); + return Files.readString(path, StandardCharsets.UTF_8); + } +} From 3673978a1a3ff61b7bdafdde885b841be310ac82 Mon Sep 17 00:00:00 2001 From: RicheyWorks <730richey730@gmail.com> Date: Tue, 26 May 2026 03:49:58 -0700 Subject: [PATCH 2/2] Core-LB-G14: Refresh PR checks