Add comments about some of the gotchas we encountered

internal/providers/testing/provider_mock.go

@@ -252,6 +252,11 @@ func (p *MockProvider) ValidateEphemeralResourceConfig(r providers.ValidateEphem
 	return resp
 }
 
+// UpgradeResourceState mocks out the response from the provider during an UpgradeResourceState RPC
+// The default logic will return the resource's state unchanged, unless other logic is defined on the mock (e.g. UpgradeResourceStateFn)
+//
+// When using this mock you may need to provide custom logic if the plugin-framework alters values in state,
+// e.g. when handling write-only attributes.
 func (p *MockProvider) UpgradeResourceState(r providers.UpgradeResourceStateRequest) (resp providers.UpgradeResourceStateResponse) {
 	p.Lock()
 	defer p.Unlock()

internal/terraform/context_apply_ephemeral_test.go

@@ -638,6 +638,8 @@ resource "ephem_write_only" "wo" {
 			},
 		},
 	}
+	// Below we force the write_only attribute's returned state to be Null, mimicking what the plugin-framework would
+	// return during an UpgradeResourceState RPC
 	ephem.UpgradeResourceStateFn = func(ursr providers.UpgradeResourceStateRequest) providers.UpgradeResourceStateResponse {
 		return providers.UpgradeResourceStateResponse{
 			UpgradedState: cty.ObjectVal(map[string]cty.Value{
@@ -658,6 +660,8 @@ resource "ephem_write_only" "wo" {
 		SourceType: ValueFromCLIArg,
 	}
 
+	// Non-empty prior state is required to trigger UpgradeResourceState logic
+	// during planning
 	priorState := states.BuildState(func(state *states.SyncState) {
 		state.SetResourceInstanceCurrent(
 			mustResourceInstanceAddr("ephem_write_only.wo"),