tech-log-backend/docs/superpowers/plans/2026-08-02-conditional-inbound-transport-boundary.md

Conditional Inbound Transport Boundary Implementation Plan

Execution: Apply TDD independently per transport, then run exact no-skip qualification and an independent read-only review before beginning P2 cleanup.

Goal: Make GraphQL, gRPC, and WebSocket opt-in status truthful, fail closed on unsafe activation, and release-blocked by real protocol evidence without adding them to the default runtime.

Task 1: Runtime Membership and Opt-In Composition

Files: src/config/architecture/modules.json, src/settings.gradle, src/build.gradle, src/app-bootstrap/build.gradle, app-bootstrap conditional transport tests

• Add and fail-closed validate exact runtime_memberships for all 19 leaves.
• Compare registry membership to both composition roots' direct production project edges.
• Add an isolated conditional-transport test classpath containing all three opt-in leaves.
• Prove the default graphs omit them and the explicit qualification graph contains them.

Task 2: gRPC Safe Activation and Wire Errors

Files: src/adapter/inbound/grpc/**

• Add RED tests for disabled bean/listener absence and safe property defaults/validation.
• Add real Netty feature RPC tests for auth success/failure and reflection disabled.
• Add RED tests for throw, onError(ApiErrorCarrier), and raw status sentinel paths.
• Implement loopback-only explicit insecure mode, required feature authentication policy, and ServerCall.close sanitization.
• Update dependencies, locks, README, and CLAUDE truthfully.

Task 3: GraphQL Real HTTP Boundary

Files: src/adapter/inbound/graphql/**

• Add random-port HTTP tests for auth, CORS, GraphiQL/introspection policy, and health.
• Add carrier/unknown exception sentinels and assert absence from the complete JSON response.
• Change production resolver/config only where the RED wire contract proves necessary.
• Update dependencies, locks, README, and CLAUDE truthfully.

Task 4: WebSocket Safe Activation and Wire Boundary

Files: src/adapter/inbound/websocket/**

• Add RED settings/disabled-context tests and real STOMP origin/auth/subscription tests.
• Add RED broker-send and ERROR-frame sentinel tests.
• Add RED no-projection/no-broadcast plus safe projection broadcast tests.
• Implement disabled default, validated settings, inbound authorization, safe error handler, and explicit primitive projection allowlist.
• Update dependencies, locks, README, and CLAUDE truthfully.

Task 5: Exact No-Skip Release Gate

Files: src/build.gradle, .github/workflows/ci-quality-gates.yml, .github/ci-gate-matrix.yml, .github/scripts/verify-gate-matrix.sh, wrapper manifest contract

• Register exact per-transport Test lanes with no-match/no-discovery/zero-skip enforcement.
• Register the aggregate conditionalTransportQualification task.
• Invoke it explicitly from the release-blocking quality job and add the gate-matrix record.
• Add semantic tests that fail if any required lane or workflow invocation disappears.

Task 6: Verification and Review

• Run each leaf check, exact qualification, app-bootstrap composition contract, dependency locks, env keys, architecture, public path, wrapper validation, and git diff --check.
• Run full test/check in proportion to the cross-cutting registry/build changes.
• Request independent read-only review; resolve all Critical/Important findings.
• Capture the batch in the LLM Wiki before final completion reporting.

Explicit P2 Deferral

• GraphQL feature schema, field auth, cost/depth, persisted queries, DataLoader, subscriptions.
• gRPC TLS/mTLS, external bind, proto compatibility, deadlines, streaming/backpressure.
• WebSocket broker relay, multi-node delivery, resume/replay, backpressure, versioned feature catalog.
• Transport dashboards, SLO alerts, and provider/ingress qualification.

Implementation status

• Completed on 2026-08-02.
• Verified by conditionalTransportQualification: GraphQL 8, gRPC 15, WebSocket 5, composition 1; skipped 0.
• Verified by the real CI gate-matrix validator and focused bypass regression tests.
• Independent review result: READY, Critical 0 / Important 0 / Minor 0.